constellation/cli

Constellation CLI design guide

This document aims to outline the design principals behind the CLI code and packages. It should be consulted by developers when making changes to the code of packages in cli/internal/.

Basic layout

cli/ consists of 2 packages, cli/cmd/, and cli/internal/, and a main.go, which serves as the entrypoint for the CLI. No new packages or files should be added to this base directory.

cli/cmd/ defines the root command of the CLI. Any changes concerning the root command, or additions like persistent flags (flags that can be accessed by all subcommands) should be added here.

TODO: Discuss: Root command could be added to cli/internal/cmd/

cli/internal/ holds the actual logic of the CLI, and will be discussed in detail in the following sections. The code is kept as internal packages to avoid accidentally exposing non public API logic of the CLI to other packages of Constellation. Any shared code should instead go into the global internal/ package.

The internal package

cli/internal/ implements logic of the CLI and is split into multiple distinct packages. Each package should aim to implement a specific functionality. Multi purposes packages should be avoided.

The following packages are listed and explained in alphabetical order. New packages should be added here when they are created.

cloudcmd

This package focuses on the interaction with the cloud provider. It separates the cloud provider specific code from the rest of the CLI, and provides a common interface for all cloud providers. Exported functions defined here should be cloud provider agnostic, meaning there should be no functions for specific CSPs. Rather the cloudcmd package should declare functions that take a cloudprovier.Provider as argument, perform CSP specific logic, and return a universally usable result.

It is used by the cmd package to handle creation of cloud resources and other CSP specific interactions.

clusterid

Defines the structure of the Constellation cluster ID file. Logic in this package should be kept minimal.

cmd

Defines the commands of the CLI. Logic should be kept to input/output parsing whenever possible. Any more complex code should usually be implemented in one of the other CLI packages.

The code here should be kept as cloud provider agnostic as possible. Any CSP specific tasks should be handled by cloudcmd.

All filepaths handled by the CLI code should originate from here. Common filepaths are defined as constants in internal/constants. To generate workspace correct filepaths for printing, use the functions from workspace.go // TODO: Discuss if we should move this to its own package

featureset

featureset defines feature gate constants for the CLI and should not implement any logic.

helm

Helm is used to manage Kubernetes deployments of a Constellation cluster. The package implements functionality to install, update, and manage Helm charts.

The charts themselves are embedded in a built CLI binary, and values are dynamically updated depending on configuration. The charts can be found in cli/internal/helm/charts/.

Helm logic should not be implemented outside this package. All values loading, parsing, installing, uninstalling, and updating of charts should be implemented here. As such, the number of exported functions should be kept minimal.

iamid

Defines the structure of the IAM service account file.

TODO: Discuss if this should be renamed. The cluster ID file was named as such because it contains the cluster ID. A similar thing is not the case for this file.

TODO: Discuss if this should be moved. Having this as a standalone package seems slightly weird, since it contains just CSP specific information generated by Terraform. Additionally the content of this struct are never written as a file, the output simply printed to the user, or written to their config. Maybe restructuring this as a return value for the IAM cloud creator would be a better fit.

kubernetes

For fetching status information updating resources in Kubernetes not directly managed by Helm, the CLI needs to interact with the Kubernetes API directly. This functionality is implemented in the kubernetes package.

The package should be used for:

• Fetching status information about the cluster
• Creating, deleting, or migrating resources not managed by Helm

The package should not be used for anything that doesn't just require the Kubernetes API. For example, Terraform and Helm actions should not be accessed by this package.

libvirt

Constellation uses libvirt to run clusters on local hardware. To enable easy deployment across different Linux distributions, the CLI can deploy libvirt inside a Docker container. The required files and Go code to start the container can be found in cli/internal/libvirt/.

The code in this package should be kept minimal, and likely won't need to be changed unless we do a major refactoring of our QEMU/libvirt installation.

terraform

Terraform is used to create cloud resources and IAM resources required for Constellation clusters. The package implements functionality to create, update, delete, and view said resources.

The Terraform files are embedded in a built CLI binary, and variables are dynamically update depending on configuration. The files can be found in cli/internal/terraform/terraform/.

Functions of this package should be kept mostly cloud agnostic (There should be no "CreateAzureCluster" function), as loading the correct values and calling the correct functions for a given CSP is handled by the cloudcmd package.

upgrade

This package implements some logic to upgrade resources for new Constellation releases.

TODO: Remove this package, since it s functionality should be implemented by other packages.