apollo builds k3s clusters from scratch.
It's Ansible-based and allows you to deploy Kubernetes clusters on any machine with a supported OS (Ubuntu, Debian, Centos) and architecture (x64, armhf, arm64) that you can access via SSH.
Depending on the provider of your machines (bare-metal or a supported cloud-provider), additional enhancements like CSI-integration are available.
- Ansible >= 2.10
- Python OpenShift
- Helm
- kubectl
- Porter (optional)
pip3 install -r requirements.txtYour inventory defines the machines you want to build your cluster upon. The composition of the cluster is out of scope for apollo. apollo expects a minimum of 1 master node.
Create a directory (the inventory_dir) for your new cluster:
mkdir -p inventory/my-clusterCreate an inventory file for your new cluster:
edit inventory/my-cluster/hosts.ymlNOTE: this must be a valid Ansible inventory; it doesn't matter if it's YAML, JSON or INI format
Setup your nodes:
# inventory/my-cluster/hosts.yml
all:
hosts:
master-0:
ansible_host: 1.2.3.4
node-0:
ansible_host: 4.5.6.7
node-1:
ansible_host: 5.6.7.8
children:
master:
hosts:
master-0:
node:
hosts:
node-0:
node-1:
k3s_cluster:
children:
master:
node:NOTE: this is pure Ansible using the defaults. Depending on your setup your inventory might look more complex or you'll need to specify additional configuration for the SSH user or a specific SSH key file to use.
In your inventory_dir, create a vars-file:
edit inventory/my-cluster/vars.ymlSetup your cluster configuration:
# inventory/my-cluster/vars.yml
ansible_ssh_user: root
csi:
provider: longhornapollo consumes an inventory and optional configuration to build a k3s cluster:
ansible-playbook install.yml -e @inventory/default-cluster/vars.yml -i inventory/default-cluster/hosts.yml --flush-cacheUpon completion, apollo will save your Kubernetes credentials in $inventory_dir/kubeconfig.yml. Use this file to connect to the cluster.
apollo is packaged as a Cloud Native Application Bundle (CNAB) and can be installed with the help of Porter.
Instructions how to install Porter can be found in the official documentation.
For a new deployment, create a new credential set:
porter credential generate myinstallationFor a new deployment, create a new parameter set:
porter parameters generate myinstallationporter install --cred myinstallation --parameter-set myinstallation --reference wearep3r/apollo myinstallationporter installations output show kubeconfig -i myinstallationDefault configuration options can be found in defaults.yml. This file will be loaded by install.yml. Additional configuration options can be set in multiple ways:
- changing the value in
defaults.yml - creating an additional configuration file (e.g.
staging.yml) containing your configuration and feeding it to ansible when executing the playbook:ansible-playbook install.yml -e @inventory/default-cluster/vars.yml -i inventory/default-cluster/staging.yml --flush-cache - setting environment variables (see table below) before running the playbook
- overwriting variables directly in the playbooks or roles
- injecting configuration by using ansible's
--extra-varsflag:ansible-playbook install.yml -e @inventory/default-cluster/vars.yml -i inventory/default-cluster/hosts.yml -e "k3s_version=v1.20.2+k3s1"
NOTE: sensitive configuration options like secrets and credentials that don't have a default need to be set before executing the playbook - either via EnvVar or as an Ansible extra-var. The playbook fails when these are not set correctly. You need to specifiy these configs EVERY TIME you run the playbook - if you change values for a configuration option Ansible will reflect this by changing the data saved to Kubernetes. Make sure to keep configuration scoped and available each time you run the playbook or you might get unxepected results
| Configuration Option | Description | Environment Variable | Default |
|---|---|---|---|
ansible_user |
The user Ansible should use to connect to the inventory hosts | ANSIBLE_USER |
root |
k3s_extra_agent_args |
Additional arguments for the k3s agent | K3S_EXTRA_AGENT_ARGS |
`` |
k3s_extra_server_args |
Additional arguments for the k3s server | K3S_EXTRA_SERVER_ARGS |
--disable traefik |
k3s_version |
k3s version | K3S_VERSION |
v1.20.2+k3s1 |
csi.provider |
Enable/Disable CSI integration for this provider | CSI_PROVIDER |
longhorn |
systemd_dir |
The directory on the remote nodes where k3s service files should go to | SYSTEM_DIR |
/etc/systemd/system |
+[__NSCFConstantString initialize] may have been in progress in another thread when fork() was called. We cannot safely call it or ignore it in the fork() child process. Crashing instead.: https://stackoverflow.com/questions/50168647/multiprocessing-causes-python-to-crash-and-gives-an-error-may-have-been-in-progr
Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull/merge requests to us. This software is primarily developed and maintained on GitLab.
We use SemVer for versioning. For the versions available see the tags on this repository.
Versions below 3.0.0 have a different feature-set. apollo v3+ is backwards incompatible. If you're running clusters based on older versions of apollo, make sure to use the correct version.
- Fabian Peter
See also the list of contributors who participated in this project.
apollo is fair-code licensed.
No. The Commons Clause that is attached to the Custom license takes away some rights. Hence, according to the definition of the Open Source Initiative (OSI), apollo is not open-source. Nonetheless, the source code is open and everyone (individuals and companies) can use it for free. However, it is not allowed to make money directly with apollo.
For instance, one cannot charge others to host or support apollo. However, to make things simpler, we grant everyone (individuals and companies) the right to offer consulting or support without prior permission as long as it is less than 20,000 EUR (€20k) per annum. If your revenue from services based on apollo is greater than €20k per annum, we'd invite you to become a partner and apply for a license. If you have any questions about this, feel free to reach out to us at [email protected].
This software is maintained and commercially supported by p3r.. You can reach us here: