Set up a local development environment with minikube

Using minikube you can quickly set up a local Kubernetes cluster to help you adding a service to Phalanx (see Add a new service to Phalanx). This page shows you how to run a Minikube cluster on macOS (amd64 or arm64) using the docker driver.

You may be able to deploy the entire Science Platform, provided that you have enough cpu and memory on your local machine. If not, you can enable only the essential services to develop with minikube.

Note

This procedure may not create a fully-operational auth system since the ingress is different from the production system. As well, this procedure does not create a TLS certificate.

Start minikube

  1. Install minikube for your platform.

  2. Start a cluster using the docker driver with the minimum recommended resources:

minikube start --driver=docker --cpus=4 --memory=8g --disk-size=100g  --kubernetes-version=1.21.5

The --kubernetes-version option can be used to specify the k8s version to use.

Enable the Ingress controller

We recommend using the minikube ingress addon to enable ingress on minikube with the NGINX Ingress Controller.

minikube addons enable ingress

Deploy the minikube environment

Requirements

  1. Install kubectl and make sure it is configured to access minikube.

  2. Install Argo CD CLI.

  3. Install Helm 3.

  4. Install Vault.

  5. Clone the Phalanx repository.

Open Phalanx’s installer/ directory:

cd installer

Install the Python dependencies (using a virtual environment is ideal):

pip install -r requirements.txt

Lastly, set the environment variables for Vault access:

export VAULT_ADDR="https://vault.lsst.codes"
export VAULT_TOKEN="<read key for minikube>"

The Vault read key for minikube is accessible from the vault_keys_json item in the LSST IT/RSP-Vault 1Password Vault. The key itself is under the k8s_operator/minikube.lsst.codes → read → id field. If you do not have Vault access, ask SQuaRE for the minikube Vault read key. See also Secrets.

Enable essential services

Set up a Phalanx branch for your local minikube deployment

The install.sh uses the locally checked out branch of your Phalanx repository clone.

To conserve resources, you may want to deploy a subset of Phalanx services in your local minikube cluster. You can do this by editing the /science-platform/values-minikube.yaml file. Set any service you do not want to deploy to enabled: false.

Commit any changes with Git into a development branch of the Phalanx repository. You must also push this development branch to the GitHub origin, https://github.com/lsst-sqre/phalanx.git. The install.sh script uses your locally-checked out branch of Phalanx, but also requires that the branch be accessible from GitHub.

Services that must be disabled for local Minikube:

  • ingress-nginx (conflicts with the minikube addon of Nginx Ingress Controller)

Minimal set of services that should be enabled:

  • vault_secrets_operator (for Vault secrets)

  • gafaelfawr (for authentication)

  • postgreql (for gafaelfawr)

Run the installer

Finally, run the installer for the minikube environment.

./install.sh minikube $VAULT_TOKEN

Access the Argo CD UI

Add the following line to /etc/hosts.

127.0.0.1 minikube.lsst.codes

On a new terminal, use minikube tunnel to route traffic from the host to the services in minikube.

minikube tunnel

Access the Argo CD UI on http://minikube.lsst.codes/argo-cd. The minikube Argo CD admin password can be retrieved from Vault.

VAULT_PATH_PREFIX=`yq -r .vault_path_prefix ../science-platform/values-minikube.yaml`
vault kv get --field=argocd.admin.plaintext_password $VAULT_PATH_PREFIX/installer

With Argo CD you can sync your service (see Syncing Argo CD).