Skip to main content

Quickstart Tutorial

This tutorial provides a walkthrough of the KubeStrap platform. It should take ~10 minutes to get your local repo set up, and about 15 minutes for AWS or GCP to provision your infrastructure.​

Getting Started​

  1. Fork the repo here

    Note: you must fork for the bootstrap to work

  2. Clone your forked repo to local
  3. From the root of your cloned repo execute ./util/dep-check.sh to check for existence of KubeStrap's dependencies

    For any missing dependencies see dependencies

info

For the rest of the tutorial you'll need to auth to your cloud provider: AWS or GCP

Going to Production in minutes​

Create the Terraform backend config​

  1. Execute one of these:
    • AWS: ./util/create-s3-bucket.sh
    • GCP: ./util/create-gcs-bucket.sh
  2. AWS Only: Update the profile param in aws/backend.tf
tip

If you have a backend config already just update <provider>/backend.tf

Create a .tfvars file​

Create a .tfvars file in the aws or gcp directory and deploy the podinfo app. Replace values as necessary.​

aws/.tfvars or gcp/.tfvars
domain                 = "podinfo.kubestrap.it"
admin_instance_enabled = false
sops_kms_enabled       = false
enable_flux_bootstrap  = true
github_repo_branch     = "main"
github_repo = "kubestrap"

# Replace these
github_org       = "YOUR_ORG"
github_token     = "YOUR_TOKEN"
cert_admin_email = "YOUR_ADMIN_EMAIL"
info

Need help setting up a GitHub Token?

Append this for AWS​

aws/.tfvars
aws_profile = "YOUR_AWS_PROFILE"

Append this for GCP​

gcp/.tfvars
billing_account = "******-******-******"
project_id      = "YOUR_PROJECT_ID"
info

Have your own domain? Read this

Create your Cloud Infra using Terraform​

tip

For AWS: be sure to export AWS_PROFILE or set profile in backend.tf (recommended)

From the aws or gcp directory:​

terraform init && terraform apply --var-file .tfvars -auto-approve

This step can take up to 15 minutes and has successfully created your cloud infra and bootstrapped the cluster with FluxCD. It also created .kubeconfig and (optionally) .sops.yaml

To persist changes commit and push backend.tf. Note: .tfvars is git ignored.

At this point, some of your cluster apps are broken! Fix them:​

  1. Pull Flux's changes from the remote repo
  2. Execute
    • ./cluster/manifest-aws/init.sh or
    • ./cluster/manifest-gcp/init.sh
  3. Commit and push the patched files to the remote branch specified in .tfvars parameter github_repo_branch
note

This only needs to be done once

Test​

It will take several minutes for your cluster to boot up for the first time. Use your favorite Kubernetes client to view LoadBalancer IP provisioning, node autoscaling, and pod readiness before beginning this step. Or wait, like 5 minutes.

  1. Fetch your Context and Istio Ingress Hostname

    AWS​

    # cd aws
    export CONTEXT=$(kubectl --kubeconfig .kubeconfig config get-contexts -o name)
    export INGRESS_HOST=$(kubectl --kubeconfig .kubeconfig --context $CONTEXT get svc -n istio-ingress -o json | jq -r '.items.[0].status.loadBalancer.ingress[0].hostname')

    GCP​

    # cd gcp
    export CONTEXT=$(kubectl --kubeconfig .kubeconfig config get-contexts -o name)
    export INGRESS_HOST=$(kubectl --kubeconfig .kubeconfig --context $CONTEXT get svc -n istio-ingress -o json | jq -r '.items.[0].status.loadBalancer.ingress[0].ip')

  2. Curl your website!

    curl -H Host:test.podinfo.kubestrap.it http://$INGRESS_HOST
info

If you have a registered domain, see DNS docs to set it up

Cleanup​

To destroy gracefully, follow these steps​

  1. GCP only: The only way to delete KMS keys in GCP is to delete the project. Drop the key from state to avoid error on delete 
    terraform state rm 'module.sops_kms[0].google_kms_crypto_key.key[0]'
  2. Terraform Destroy 
    terraform destroy -var-file .tfvars -auto-approve
  3. Delete state bucket via console or cli

Congrats!​

You have successfully created your production infrastructure in minutes with KubeStrap. What's next?​

Etc.​

Generating a GitHub token for FluxCD​

For accessing the GitHub API, the boostrap command requires a GitHub personal access token (PAT) with administration permissions.

See: Guthub How-To