Skip to content



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


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.


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 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.


Plugins need and provide certain functionalities. This way a dependency system can be established even for custom 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. Plugins may have dependencies (implemented by needs and provides) that imply constraints to the order the plugins should be installed in.

The active plugins for a stack are defined in stack.plugins:

  name: my-cloudstack
  exposed: true
  tls: false
    - prometheus_crds
    - eventrouter
    - prometheus
    - loki
    - promtail
    - nginx_ingress
    - portainer

If you want to install or uninstall a plugin, it has to be added to this list.


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.


A plugin can be configured in the plugins configuration section of a Stackfile.


      token: YOUR_TOKEN_HERE
        count: 3
        type: cx31
        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
  • needs: a list of arbitrary strings that can be matched with a provides list
  • provides: a list of arbitrary strings that can be matched with a needs list
  • rejects: a list of plugins that can't be used together with this plugin


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.

Needs and provides

A plugin needs and provides certain functionality. By matching the needs and provides of the active plugins in a stack, a loose dependency system can be established. For example, the plugin k3s provides functionality kubernetes which plugin cert_manager needs. Plugin k3s also needs functionality vms which hcloud_vms provides.

Core plugins

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

Learn more: Core plugins

Custom plugins

Custom plugins are living in a plugins directory inside the context directory. Each plugin must have a dedicated directory having the plugin's name. Inside the plugin directory, any files are allowed. Cloudstack is looking for a file called Shipfile that must contain a plugins section (see plugin configuration) that holds the configuration for the custom plugin - especially the commands used to install and uninstall the plugin.

Learn more: Core plugins

# Shipfile
    version: 1.2.3
    subdomain: customdomain
      foo: bar
        foo: bar
          - echo "Install"
          - echo "Uninstall"


The version key of the plugin config is required.


The script section of a plugin command can hold arbitrary commands. The list will be concatenated to a Bash script and executed when you call cloudstack plugins my_custom_plugin install (or any of the commands you specified).

While install and uninstall are required commands, 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 base on debian buster so you're free to install any additional software as part of a plugin command.


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).


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


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


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.


The Shipfile contains configuration for Custom plugins. Its default location is the plugin's directory inside the plugins folder of the context directory.


The Statefile contains the current state of the stack. It gets updated everytime a CLI command is invoked.

Last update: November 6, 2021
Back to top