Skip to content

Suite CLI

The ITsynch Suite includes a CLI called suite that is mainly used for development and deployment purposes. The CLI is developed using the Suite Framework itself and is located in the Suite monorepo.

It is available by default on the devcontainer and activated deployment environment and can be invoked using the suite program:

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
$ suite --help
Description:
  Suite CLI. Automation and tooling for DevEx & DevOps
  See more at: https://docs.suite.itsynch.com/development/suite-cli
  Developed with ❤️  by ITsynch

Usage:
  suite [command] [options]

Options:
  --version                                                    Show version information
  -?, -h, --help                                               Show help and usage information
  --log-level <Debug|Error|Fatal|Information|Verbose|Warning>  Allows configuring logging verbosity [default: Information]

Commands:
  container    Application Manifest actions for OCI Containers
  app          Application Manifest specific actions
  database     Application manifest database actions
  environment  Environment actions

Global arguments

  1. --log-level All commands support configuring the log level which allows you to drill down into what the CLI is doing under the hood. Verbose gives you everything. Information is the default. We recommend using Debug for initial troubleshooting.

Manifests

In order to simplify the monorepo management and improve DevEx, several YAML Manifests files have been introduced. The Suite CLI supports scaffolding and interacting with these manifests.

Application Manifest

The Application Manifest is a deployable workload which is described inside an application.yaml file. Currently, dotnet and angular applications are supported.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
apiVersion: devops.itsynch.com/v1
kind: Application
metadata:
    name: suite-home-ui
spec:
    boundedContext: SuiteHome
    destination:
        - hub
        - satellite

    build:
        angular:

  1. The metadata.name will be used to conventionally determine several things like container image names, kubernetes service names, etc.

  2. The spec.destination determines where this service should be deployed. Usually hub and satellite but others could be used as well. The CLI does not restrict this field to any values, these act similar to labels/annotations.

  3. The spec.build determines how this application should be built. These allows configuring several stuff depending on the application kind.

Application Processors

The Suite CLI supports several processors for applications. These processors all support a --from argument which tells it where to recursively discover Application Manifests from.

For example, for building container images:

Bash
1
2
3
4
5
    # no apps provided, will build all discovering from dotnet and angular
    suite app container build --from ./dotnet --from ./angular

    # build specific apps (--from defaults to current working directory)
    suite app container build admin-center-app sharing-levels

For example, for generating database scripts:

Bash
1
2
    # generate the currencies.sql script
    suite app database script --from ../dotnet currencies

GraphQL Fusion Schema

In GraphQL Fusion, each backend service needs to generate its GraphQL Schema and a Sub Graph Package for each gateway they publish to. The Sub Graph Package includes the backend's schema, configuration file, and extension file for the target gateway.

The CLI supports generating the GraphQL schema and Sub Graph Package for applications, particularly for backend services.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
apiVersion: devops.itsynch.com/v1
kind: Application
metadata:
    name: test-app
spec:
    boundedContext: SuiteTesting
    destination:
        - hub
        - satellite
    build:
        dotnet:
            graphql:
                publish: # configures this backend to publish to the below gateways
                    - gateway: test-app-bff
                      extensions:
                          - my-custom.extension.gql
                          - other.gql

We can then invoke the CLI to generate the schema and sub graph. The below command outputs a schema.graphql and a test-app-bff.fsp file for each gateway inside the application's directory.

Note

An application can publish to multiple gateways each one having multiple extension files.

Bash
1
suite app graphql schema test-app

For applications that do not publish to any gateway and simply need their schema generated (for validation purposes, etc):

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
apiVersion: devops.itsynch.com/v1
kind: Application
metadata:
    name: test-app
spec:
    boundedContext: SuiteTesting
    destination:
        - hub
        - satellite
    build:
        dotnet:
            graphql:
                enable: true # enables schema generation without publishing to any gateway

GraphQL Fusion Gateway Package

For gateways / backends for frontends we need to generate the Fusion Gateway Package, which composes all sub graphs that publish to this gateway in a single package for the gateway to use.

The BFF manifest is quite simple since there's an inversion of control where each backend configures which gateway it publishes to. We only need to configure the ServiceKind to let the CLI know that this dotnet application is actually a BFF.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
apiVersion: devops.itsynch.com/v1
kind: Application
metadata:
    name: test-app-bff
spec:
    build:
        dotnet:
            kind: BackendForFrontend
            migrations:
                enable: false

In order to generate the gateway.fgp file that is needed for fusion, we can run the below command:

Bash
1
suite app graphql compose test-app-bff

This command will build the schema for each subgraph publishing to this gateway, and will the compose all sub graphs into the gateway.fgp file which is required on runtime by Fusion.

Environment Manifest

An Environment consists of several applications that need to be deployed several Destinations. File system discovery is used to retrieve the list of applications. Filters can then be applied to select specific applications.

The Environment contains a list of Destinations where such Applications need to be deployed. In order to map which applications should be deployed to which environment, the applications specify the target destination group, and each destination specifies to which group it belongs to.

YAML
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
apiVersion: devops.itsynch.com/v1
kind: Environment
metadata:
    name: sample-env
    labels:
        devops.itsynch.com/customer: <TOO>
spec:
    applications:
        discovery:
            - ./angular
        filters:
            - name: suite-home-ui
    destinations:
        office:
            group: hub
            version: v1.2.3
Bash
1
suite environment update ./devops/environments/some-corp/sample-env/environment.yaml

The command will generate the files to kickstart an environment from scratch using the provided environment.yaml file.

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
.sample-env
  environment.yaml
  office
    v1.2.3
      database
        001_addresses.sql
        [..]
      deployment
        addresses
          appsettings.json
          addresses.yaml
        data-seeder
          [all files].json
          data-seeder.yaml
        [..]
      migrations-tail.yaml
    [..]
  demo-satellite
    [..]
  1. database: SQL scripts to be run to create the DB structure.
  2. deployment: k8s deployment manifests
  3. migrations-tail.yaml latest migration name/id for each application

suite environment update does the below:

Database Scripts / Migrations

When updating an environment we need to generate the DB scripts for each application by executing dotnet ef migration script <args>. For a fresh environment, that works ok. For updating an environment, we need to execute it providing using the from argument to tell it from which migration to generate the script. This generates only the updating sql statements from migration A to B. Each application has a different migration name, hence we cannot execute it using a single migration name.

The migrations-tail.yaml is generated when an environment is updated. It contains a map of each application to it's latest migration. When updating an environment from an existing version, this file will be used to obtain the latest migration for each application in order to generate the script diff.