Set up a local development environment with minikube#

Using minikube you can quickly set up a local Kubernetes cluster to help you develop and test an application for Phalanx (see Add a new application 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 applications to develop with minikube.

Warning

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.

Instead, the recommended pattern for developing an application in a Kubernetes cluster is to use a development environment. See Deploying from a branch for development for details.

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 management overview.

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 applications in your local minikube cluster. You can do this by editing the /environments/values-minikube.yaml file. Set any application 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.

Application that must be disabled for local Minikube:

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

Minimal set of applications that should be enabled:

  • vault-secrets-operator (for Vault secrets)

  • gafaelfawr (for authentication)

  • postgresql (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 application 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 .vaultPathPrefix ../environments/values-minikube.yaml`
vault kv get --field=argocd.admin.plaintext_password $VAULT_PATH_PREFIX/installer

With Argo CD you can sync your application (see Syncing Argo CD in an environment).