All the Cloudstack magic happens inside of a Docker container running on the system that invokes the
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.
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.
The inventory is a regular, yaml-formated Ansible inventory inside the context directory. The inventory must be named
The inventory can be created automatically through plugins (such as hcloud_vms) or provided manually.
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
kubernetes. Some plugins (like k3s) can be used to install Kubernetes - they
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.
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.
A plugin can be configured in the
plugins configuration section of a Stackfile or in its
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.hostnamethat the plugin will be exposed to (if
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
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 are maintained by Ayedo Cloud Solutions GmbH and part of the Cloudstack code base.
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"
version key of the plugin config is required.
A plugin can expose an arbitrary amount of commands. Commands can be used to implement the actual functionality of a plugin. Examples would be
uninstall, but also
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).
uninstall should be defined by convention, you're free to implement anything here. Command names are limited to certain characters though:
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.
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 and inventory 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 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 are ordered sequences of commands. They can be used to build bootstrap or teardown automations or to install/uninstall plugins in a certain order.
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 [...]
When a valid inventory is given, you can use
cloudstack ssh $HOST_FROM_INVENTORY to ssh directly into that host.