What is apollo?

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.

Prerequisites

• Ansible >= 2.10
• Python OpenShift
• Helm
• kubectl
• Porter (optional)

Install with pip

pip3 install -r requirements.txt

Get started

Create your inventory

Your 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-cluster

Create an inventory file for your new cluster:

edit inventory/my-cluster/hosts.yml

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

Create your configuration files

In your inventory_dir, create a vars-file:

edit inventory/my-cluster/vars.yml

Setup your cluster configuration:

# inventory/my-cluster/vars.yml
ansible_ssh_user: root
csi:
  provider: longhorn

Run apollo

apollo 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-cache

Upon completion, apollo will save your Kubernetes credentials in $inventory_dir/kubeconfig.yml. Use this file to connect to the cluster.

Use Porter

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.

Generate credential set

For a new deployment, create a new credential set:

porter credential generate myinstallation

Generate parameter set

For a new deployment, create a new parameter set:

porter parameters generate myinstallation

Install Bundle

porter install --cred myinstallation --parameter-set myinstallation --reference wearep3r/apollo myinstallation

Get kubeconfig

porter installations output show kubeconfig -i myinstallation

Configuration

Default 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-vars flag: 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 options

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

Issues / Troubleshooting

• +[__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

Contributing

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.

Versioning

We use SemVer for versioning. For the versions available see the tags on this repository.

Older versions

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.

Authors

• Fabian Peter

See also the list of contributors who participated in this project.

License

apollo is fair-code licensed.

Is apollo Open-Source

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 info@p3r.one.

Disclaimer

This software is maintained and commercially supported by p3r.. You can reach us here:

• Web
• Slack
• GitLab
• GitHub
• LinkedIn