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
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. Plugins may have dependencies (implemented by
provides) that imply constraints to the order the plugins should be installed in.
The active plugins for a stack are defined in
stack: name: my-cloudstack hostname: my.cloudstack.one exposed: true tls: false plugins: - 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.
... plugins: hcloud_vms: 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
needs: a list of arbitrary strings that can be matched with a
provides: a list of arbitrary strings that can be matched with a
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¶
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.
Learn more: Core 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 plugins: my_custom_plugin: 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.
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).
uninstall are required commands, 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 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).
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 Statefile contains the current state of the stack. It gets updated everytime a CLI command is invoked.