Reference

Container

All the Cloudstack magic happens inside of a Docker container running on the system that invokes the cloudstack command.

The container will be started whenever you call a plugin command. It is based on public image provided by ayedo (see the Dockerfile here) and contains most of the best-practice tooling of cloud-native development and operations.

Stack

Whatever you build with Cloudstack is called a stack. It's a named instantiation of the configuration in your context directory.

Context

The context directory contains the configuration and lifecycle artifacts of a stack. It's a directory on your filesystem that can be synced and collaborated on via git.

Inventory

The inventory is a regular, yaml-formated Ansible inventory inside the context directory. The inventory must be named inventory.yml.

The inventory can be created automatically through plugins (such as hcloud_vms) or provided manually.

Kubeconfig

Cloudstack is tightly integrated with Kubernetes and can connect to a cluster using a kubeconfig file. By default, the CLI looks for a kubeconfig file in $HOME/.kube/config and in the KUBECONFIG environment variable.

When working with a stack (e.g. by invoking cloudstack from within a context directory or using the --context flag), the CLI looks for a kubeconfig.yml file within the context directory. If it finds one, this has precedence over a kubeconfig file discovered from the default path or the environment.

Additionally, you can specify a kubeconfig file using the --kubeconfig PATH/TO/YOUR/kubeconfig flag.

Kubernetes

Kubernetes is the container orchestrator of choice in Cloudstack. Most of the plugins (like prometheus) are directly depending on Kubernetes - they have a need for kubernetes. Some plugins (like k3s) can be used to install Kubernetes - they provide kubernetes.

Note

Plugins need and provide certain functionalities. This way a dependency system can be established even for custom plugins.

Plugins

Cloudstack is a modular system built of plugins that provide the actual functionality. A stack is composed of one or more plugins and their configuration.

Note

The order in which plugins are installed is important. For example, the prometheus and nginx_ingress plugin needs the Prometheus CRDs to be available in the cluster, so they can install a ServiceMonitor that enabled automated monitoring. Thus, the plugin prometheus_crds must be installed before the other plugins.

Use Pipelines to define bootstrap or teardown sequences for your stack.

Configuration

A plugin can be configured in the plugins configuration section of a Stackfile or in its Pluginfile (the Pluginfile must reside in the plugin's directory).

# Stackfile
[...]
plugins:
  hcloud_vms:
    config:
      token: YOUR_TOKEN_HERE
      master:
        count: 3
        type: cx31
      node:
        count: 3
        type: cpx31
[...]

# plugins/hcloud_vms/Pluginfile
[...]
config:
  token: YOUR_TOKEN_HERE
  master:
    count: 3
    type: cx31
  node:
    count: 3
    type: cpx31
[...]

Each plugin has a shared set of configuration:

• version: the version of the plugin to be installed. For most plugins, this equals to the application version of the plugin
• subdomain: the subdomain under stack.hostname that the plugin will be exposed to (if exposed is true)
• namespace (only applies to plugins that will be installed into Kubernetes): the namespace the plugin will be installed to
• chart: this section holds configuration for Helm-based plugins. For Core plugins this should be left untouched. It can be useful to customize this for Custom plugins
• config: plugin-specific configuration that is not common to all plugins belongs here
• commands: an array of commands that the plugin implements. Defaults to install and uninstall

Note

To see the default configuration, run cloudstack show defaults. The default output format is yaml. If you prefer JSON, add --output-format json to the command. To see the rendered stack configuration, use cloudstack show config.

Core plugins

Core plugins are maintained by Ayedo Cloud Solutions GmbH and part of the Cloudstack code base.

Custom plugins

Custom plugins are living in a plugins directory inside the context directory. Each plugin must have a dedicated directory named by the plugin's name. Inside the plugin directory, any files are allowed. Cloudstack is looking for a file called Pluginfile that must contain the plugin's configuration (see plugin configuration). Usually the Pluginfile is used for a plugin's default configuration (like the commands it supports) while instance-specific configuration belongs into the Stackfile.

# Pluginfile
version: 1.2.3
subdomain: customdomain
config:
  foo: bar
  baz:
    foo: bar
commands:
  install:
    script:
      - echo "Install"
  uninstall:
    script:
      - echo "Uninstall"

Note

The version key of the plugin config is required.

Commands

A plugin can expose an arbitrary amount of commands. Commands can be used to implement the actual functionality of a plugin. Examples would be install or uninstall, but also status or debug.

The script section of a plugin command is a list of commands that will be concatenated to a Bash script and executed inside the Cloudstck container when you call cloudstack plugins my_custom_plugin install (or any of the commands you specified).

While install and uninstall should be defined by convention, you're free to implement anything here. Command names are limited to certain characters though: a-zA-Z_.

The script will be executed within a container created from the Cloudstack image and has access to all the tools available in the container (namely kubectl, helm, ansible, cloudstack, etc). The context directory is available at /context, the active kubeconfig file is mounted to /root/.kube/config and set via KUBECONFIG environment variable so all the tooling should work out of the box.

The Cloudstack image is based on debian buster so you're free to install any additional software as part of a plugin command.

Note

Cloudstack does not persist data between invocations apart from changes made to the context directory (mounted at /context inside the execution container) or the kubeconfig file (mounted at /root/.kube/config inside the execution container).

Note

It's fine to write data to the context directory. It's advised to not touch the kubeconfig and inventory file unless you're absolutely sure what you do as it might affect your whole stack.

Stackfile

The Stackfile holds the configuration for a stack. Its default location is the context directory, but it can be anywhere on your system.

Note

You can specify a custom Stackfile with the CLI by using --stackfile YOUR/CUSTOM/Stackfile. This can be especially helpful when using Cloudstack in CI.

Pluginfile

The Pluginfile contains configuration for Custom plugins. Its default location is the plugin's directory inside the plugins folder of the context directory. See Configuration for an example Pluginfile.

Pipelines

Pipelines are ordered sequences of commands. They can be used to build bootstrap or teardown automations or to install/uninstall plugins in a certain order.

Note

In earlier versions of Cloudstack there was a launch command which called the install command of all plugins listed in stack.plugins. This has been deprecated. You can build a pipeline called install that runs your plugins in the required order and then use cloudstack pipelines run install to achieve the same goal. See the example below.

# Stackfile
pipelines:
  install:
    steps:
      - name: install hcloud_vms
        plugin: hcloud_vms
        command: install
      - name: install k3s
        plugin: hcloud_vms
        command: install
[...]

SSH

When a valid inventory is given, you can use cloudstack ssh $HOST_FROM_INVENTORY to ssh directly into that host.

---

Last update: June 2, 2022