Skip to main content

Install DevOps from the CLI

Prerequisites​

You can download the latest build for your architecture from the releases page. Once done, extract it, and ensure it's executable. You may need to use sudo for the tar or `chmod`` command.

tar --overwrite -xvf devops_<VERSION>_linux_<ARCH>.tar.gz -C /usr/local/bin/ devops && \
chmod +x /usr/local/bin/devops

Now you can run devops.

devops version

Docker Desktop​

Install Docker Desktop.

info

If you are a Windows user, you need to be sure to enable Docker support in WSL2 distributions. More information in the Docker documentation.

Docker Resources Allocation​

The more resources you give Docker, the faster your cluster creation will go, but here are the minimum requirements:

  • CPU: 5 Cores
  • Memory (RAM): 5 GB
  • Swap: 1 GB
  • Virtual Disk limit (for Docker images & containers): 10 GB

If you pull multiple images from Docker Hub, you may reach the rate limit: to help this issue not happening, we suggest you log in to your account (you can create a free one) in Docker Desktop. At the time of writing this docs, the limit is doubled when signed in.

GitHub​

Create or use an actual GitHub personal account

Install the CA (Certificate Authority) of mkcert in your trusted store​

We use mkcert to generate local certificates and serve https with the Traefik Ingress Controller. During the installation, DevOps generates these certificates and pushes them to Kubernetes as secrets to attach to Ingress resources.

To allow the applications running in your DevOps platform in addition to your browser to trust the certificates generated by your DevOps local install, you need to install the CA (Certificate Authority) of mkcert in your trusted store. To do so, follow these simple steps:

brew install mkcert
mkcert -install

This is not an optional step: the cluster creation will fail if you don't install the mkcert CA in your trusted store.

If you are using Firefox, you have one more step: you need to install the Network Security Services (NSS):

brew install nss

Additional steps for Windows with WSL​

The certificate installed on your WSL distribution won't be propagated to the local system (Windows). If you want to access your k3d installation from your main OS without certification warning, you will need to add the certificate to your Windows Trusted Root Certification Authorities store. To do so, find the location of the store by running the following command in WLS:

mkcert -CAROOT

Now cd into that directory and run:

explorer.exe .

It will open Explorer in the current directory. Copy the full path, which should look like \\wsl.localhost\Ubuntu\root\.local\share\mkcert. Open PowerShell as an administrator, cd to the copied path, and run the following command:

certutil –addstore -enterprise –f "Root" .\rootCA.pem

Restart your browser, and you should be good to go.

Local Atlantis Executions (optional)​

To install the k3d DevOps platform with Atlantis wired up for automated Terraform executions, you'll need to create an account with ngrok, and expose an ngrok auth token environment variable in your shell. This allows the GitHub/GitLab servers to invoke the Atlantis webhook running in your cluster.

You can sign up for an ngrok account for free.

Once you've logged in, you can retrieve your ngrok auth token.

Make this available by running the following in your shell before you execute your devops k3d create command, replacing the xxxxxxxxxxxxxxxxxxxxx with your actual authtoken.

export NGROK_AUTHTOKEN=xxxxxxxxxxxxxxxxxxxxx

If you skip this step the platform will still operate just fine, you just won't have automated Terraform plans and applies in your pull requests.

Working without SSH​

If you need your DevOps installation to avoid using SSH whenever possible, you can bypass SSH and DevOps will configure itself, GitHub Actions, Argo CD, and your entire GitOps workflow to utilize HTTPS instead of SSH at all times.

Provide the flag --git-protocol https when building your k3d cluster and DevOps will take care of the rest.

If you ever need to change this, you will need to rebuild the cluster or manually update the templates in your gitops repository.

Create your new local cluster​

To create a new DevOps cluster locally, run

devops k3d create

devops k3d create --git-protocol https

Details about your execution will be logged to your ~/.k1/logs directory. More information on devops k3d, including optional flags, can be discovered by running devops k3d help.

We are able to create an ephemeral GitHub token that expires after 8 hours using a process that will prompt your browser to request access to your account. If you need a quick environment, this is a frictionless approach. However, if you need this environment for longer than 8 hours, which is probably the case, please follow our GitHub Token Guide and export a more permanent token to your terminal by using the following command:

export GITHUB_TOKEN=ghp_xxxxxxxx

Installed Applications​

To see what is installed by DevOps, check the overview page.

Root credentials​

To obtain your 3 initial passwords, run

devops root-credentials

If you created your cluster using the UI, or reset your DevOps environment, you can still retrieve the root credentials (except the kbot user password, which you will have to find manually in Vault) using kubectl:

# Argo CD admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Vault root token
kubectl -n vault get secret vault-unseal-secret -o jsonpath="{.data.root-token}" | base64 -d

Connecting to Kubernetes​

You will be automatically connected to your new Kubernetes cluster. To view all cluster pods, run

kubectl get pods -A