Skip to content

Latest commit

 

History

History
125 lines (97 loc) · 3.15 KB

quick-start.md

File metadata and controls

125 lines (97 loc) · 3.15 KB

Quick Start

In this quick starter guide you will deploy Heist globally in a Kubernetes cluster and create an auto generated secret.

You will need the following prerequisites:

  • Kubernetes cluster
  • HashiCorp Vault
  • Helm
  • Heist CLI

Install Heist CLI

You can install the Heist CLI by downloading the latest release from our GitHub page or by installing it via go install.

Configure Vault

This requires admin permission in Vault. Set a token with admin privileges in the VAULT_TOKEN environment variable and then fill in the necessary information in the following commands:

Vault running in Kubernetes

This configures necessary permissions in your in-cluster vault instance.

heist setup k8s \
  --vault-namespace "VAULT_NAMESPACE" \
  --vault-service "VAULT_SERVICE" \
  --vault-port "8200" \
  --vault-token "${VAULT_TOKEN}"

Vault running outside of Kubernetes

This configures necessary permissions in your external vault instance.

heist setup static \
  --vault-url "https://your.vault.instance.com" \
  --vault-token "${VAULT_TOKEN}" \
  --kubernetes-jwt-ca-cert "$(cat kubernetes_jwt_ca_cert.pem)" \
  --kubernetes-jwt-issuer "KUBERNETES_JWT_ISSUER"

Deploy Heist

By executing the following commands, you will deploy Heist to the namespace heist-system and should be ready for use immediately.

helm repo add youniqx-oss https://youniqx.github.io/helm-charts
helm repo update
helm install heist youniqx-oss/heist

Deploy test secret

First, you have to generate a Vault KV secret engine. You can do this by deploying a VaultKVSecretEngine CRD called test-engine. It will create a KV secret engine at managed/<namespace>/test-engine.

apiVersion: heist.youniqx.com/v1alpha1
kind: VaultKVSecretEngine
metadata:
  name: test-engine

Afterwards you can deploy an auto generated secret which will be stored within the previously created KV secret engine.

apiVersion: heist.youniqx.com/v1alpha1
kind: VaultKVSecret
metadata:
  name: test-secret
spec:
  engine: test-engine
  fields:
    test-field:
      autoGenerated: true

The KV secret engine managed/<namespace>/test-engine should now contain a secret called test-secret with a single field called test-field which should contain a 64 character long auto generated value.

cat<EOF | kubectl apply -f -
apiVersion: heist.youniqx.com/v1alpha1
kind: VaultKVSecretEngine
metadata:
  name: test-engine
---
apiVersion: heist.youniqx.com/v1alpha1
kind: VaultKVSecret
metadata:
  name: test-secret
spec:
  engine: test-engine
  fields:
    test-field:
      autoGenerated: true
EOF

Delete test secret

kubectl delete vaultkvsecretengine test-engine
kubectl delete vaultkvsecret test-secret

You should see them go into the Terminating state in your cluster for a few seconds, before they disappear completely. At the same time the engine and secret will also be deleted in your Vault instance. Check your Vault instance again and the secret engine should be gone again.

For more information refer to here to learn about the other CRDs and how to use them.