MCLI

CLI tool for managing Giant Swarm installations.

What is MCLI?

mcli is a golang based CLI tool for managing configuration for Giant Swarm management clusters. The idea is to provide a tool that allows for easier review, creation and updates of configuration data. Commands found inside the tool are based on scripts that are part of mc-bootstrap with the goal to replace more and more of them as new commands are added to mcli.

Installation

mcli can be installed as Go binary.

go install github.com/giantswarm/mcli@latest

Requirements

mcli uses the same environment variables and mechanisms as mc-bootstrap.

GitHub

Ensure that you have a valid GitHub token set in the GITHUB_TOKEN environment variable.

SOPS

For the time being, mcli uses the sops binary to encrypt and decrypt secrets in the same way as mc-bootstrap. Ensure that you have installed sops and that it is available in your PATH.

Furthermore, ensure that the SOPS_AGE_KEY environment variable is set before running a command. This is always the case when running mc-bootstrap to create a new management cluster. When using the tool to update an existing management cluster, make sure to set the SOPS_AGE_KEY environment variable to the correct value. Please only use secure mechanisms to store and retrieve this key and do not expose it in the command line. For example, if it is stored in LastPass, it can be set like this:

export SOPS_AGE_KEY=$(lpass show "Path/To/Secret/$CLUSTER.agekey" --notes)

Usage

mcli pull -c $MC_NAME > config.yaml

Use --help to learn about more options.

Commands

As most configuration is stored in git repositories, commands generally involve pulling from, pushing to, or creating repositories.

`mcli pull`

Pulls the configuration of a given management cluster and prints it to stdout. This can be used to review the configuration before making changes or to use as a base for creating a new configuration.

`mcli push`

Pushes configuration of a management cluster. This can be used to create or update a management cluster.

`mcli create`

Creates a repository. For the time being, this is only used to create a new cmc repository.

[!TIP] The tool will not print any logs unless it is run in --verbose mode.

Repositories

mcli uses a set of repositories to store configuration data.

push and pull commands will by default access all repositories below one by one to get the complete configuration. However, subcommands can be used to access only a specific repository. As of right now, the create command can only be called explicitly for the cmc repository.

`cmc`

The customer management cluster repository giantswarm/$CUSTOMER-management-clusters.

This repository contains the configuration for all management clusters of a customer. A new cmc repository is created for each customer using the mcli create cmc command.

The mcli pull cmc and mcli push cmc commands can be used to pull and push the configuration for a specific management cluster to the cmc repository.

[!IMPORTANT] When nothing else is specified via --customer or --cmc-repository flags, the tool will use the giantswarm-management-clusters repository as the default.

`installations`

The installations repository giantswarm/installations.

This repository mostly contains configuration for vintage installations. However, it also contains basic information about the management cluster. The mcli pull installations and mcli push installations commands can be used to pull and push this information to the installations repository.

Input

The tool can be used either with an input file or flags. To ease integration into mc-bootstrap, flags can be read from its environment variables and secret files.

Input file

The input file is a YAML file that contains the configuration for a management cluster. The output of an mcli pull command can be used as a base for an input file to the corresponding mcli push command. Please note that the output of mcli pull will redact sensitive information like secrets.

The file can be passed to the tool with the --input flag.

[!IMPORTANT] When using an input file via --input, the tool will ignore other configuration flags.

Flags

The tool can be used with flags to provide configuration data. To see all available flags for a command, use the --help flag. Generally, when creating a new management cluster via flags, mandatory flags need to be set. That should always be the case when running mc-bootstrap to create a new management cluster.

For updating a management cluster via flags, only the flags that need to be updated need to be set.

Environment variables

The tool can read configuration from environment variables. The available environment variables are the same as those used by mc-bootstrap. Environment variables are used to set the default values for corresponding flags.

Example usage

Some examples of how the tool can be used.

Pull management cluster configuration

Pull the configuration of mc called $CLUSTER belonging to $CUSTOMER and print it to stdout.

mcli pull --cluster $CLUSTER --customer $CUSTOMER

The output will look something like this:

installations:
  base: example.gigantic.io
  codename: $CLUSTER
  customer: $CUSTOMER
  cmc_repository: $CUSTOMER-management-clusters
  ccr_repository: $CUSTOMER-configs
  accountEngineer: Elmo
  pipeline: stable
  provider: capa
  aws:
    region: eu-central-1
    hostCluster:
      account: "12345"
      cloudtrailBucket: ""
      adminRoleARN: arn:aws:iam::12345:role/RoleName
      guardDuty: false
    guestCluster:
      account: "12345"
      cloudtrailBucket: ""
      guardDuty: false
cmc:
  agePubKey: age12345
  cluster: $CLUSTER
  clusterApp:
    name: $CLUSTER
    catalog: cluster
    version: 0.65.0
    values: |
        global:
            metadata:
            description: "example MC"
            name: "example"
            organization: "giantswarm"
        [...]
    appName: cluster-aws
  defaultApps:
    name: $CLUSTER-default-apps
    catalog: cluster
    version: v0.49.0
    values: |
      clusterName: $CLUSTER
      organization: giantswarm
      managementCluster: $CLUSTER
    appName: default-apps-aws
  clusterIntegratesDefaultApps: false
  mcAppsPreventDeletion: true
  privateCA: false
  privateMC: false
  clusterNamespace: org-giantswarm
  provider:
    name: capa
  taylorBotToken: REDACTED
  sshDeployKey:
    key: REDACTED
    identity: REDACTED
    knownHosts: |
      github.com ecdsa-sha2...
  customerDeployKey:
    key: REDACTED
    identity: REDACTED
    knownHosts: |
      github.com ecdsa-sha2...
  sharedDeployKey:
    key: REDACTED
    identity: REDACTED
    knownHosts: |
      github.com ecdsa-sha2...
  certManagerDNSChallenge:
    enabled: false
  configureContainerRegistries:
    enabled: true
    values: REDACTED
  customCoreDNS:
    enabled: false
  disableDenyAllNetPol: false
  mcProxy:
    enabled: false
  baseDomain: awstest.gigantic.io
  gitOps:
    cmcRepository: $CUSTOMER-management-clusters
    cmcBranch: $CLUSTER_auto_branch
    mcbBranchSource: main
    configBranch: $CLUSTER_auto_config
    mcAppCollectionBranch: $CLUSTER_auto_branch

Alternatively, the cmc and installations repositories can be accessed separately.

mcli pull cmc --cluster $CLUSTER --customer $CUSTOMER

mcli pull installations --cluster $CLUSTER

If needed, the REDACTED secrets can be displayed in the output by setting the --display-secrets flag.

[!WARNING] It's important to be careful with the --display-secrets flag as it will print sensitive information in the output. Only use it when necessary.

Create management cluster repository

Create a new management cluster repository for $CUSTOMER

mcli create cmc --customer $CUSTOMER -v

[!TIP] The -v flag is used to print logs to stdout.

The result will be a new repository in the giantswarm organization called $CUSTOMER-management-clusters. Also, a pull request in the giantswarm/github repository will be created to add the new repository.

Push management cluster configuration

In order to push the configuration of a new management cluster, a couple of secrets need to be created first. Usually, this will be done in the process of running mc-bootstrap to create a new management cluster.

To create entirely new configuration for testing or otherwise, a new age key pair can be generated via the age-keygen command.
More information on the various secrets and values can be found in the mc-bootstrap repository.
The output of the mcli pull command can be used as a base for the input file.

Below examples assume that the cluster either already exists and we are updating it or that the needed secrets are already created and present in the input file or secret folder.

With an input file

Push the configuration of mc called $CLUSTER belonging to $CUSTOMER to repositories.

mcli push --cluster $CLUSTER --customer $CUSTOMER --input config.yaml

A succesful push should print the resulting configuration to stdout in the same way as the pull command. It should also create a new branch in the affected repositories.