From 32a9a4ac71b6e8a405fa9a66e106efab6fdd07a0 Mon Sep 17 00:00:00 2001 From: Igor Rodionov Date: Wed, 23 May 2018 05:01:58 +0600 Subject: [PATCH] Document Ingress Setup (#77) --- content/geodesic/module/_index.md | 2 +- .../module/{usage => }/examples/Dockerfile | 0 .../{usage => }/examples/assume-role.txt | 0 .../{usage => }/examples/aws-kops-backend.tf | 0 .../examples/exit-geodesic-shell.txt | 0 .../{usage => }/examples/kops-create.txt | 0 .../examples/kops-update-cluster-initial.txt | 0 .../examples/start-geodesic-shell.txt | 0 .../terraform-apply-kops-state-backend.txt | 0 .../terraform-apply-tfstate-backend.txt | 0 .../{usage => }/examples/tfstate-backend.tf | 0 .../{usage/_index.md => module-usage.md} | 5 +- .../geodesic/module/{usage => }/with-kops.md | 58 ++++++++---- .../module/{usage => }/with-terraform.md | 20 ++--- content/glossary/e2e.md | 8 ++ content/glossary/helm-chart.md | 13 +++ content/glossary/helm.md | 10 +++ content/glossary/iam.md | 11 +++ content/glossary/mfa.md | 1 + content/kubernetes-backing-services/_index.md | 9 +- .../iam/examples/kube2iam-helmfile.yaml | 36 ++++++++ .../examples/kube2iam-usage-deployment.yaml | 18 ++++ .../iam/examples/kube2iam-usage-helmfile.yaml | 11 +++ .../iam/examples/kube2iam-usage-values.yaml | 3 + .../iam/kube2iam.md | 88 ++++++++++++++++--- .../ingress/nginx-ingress-controller.md | 2 +- .../examples/kube-lego-helmfile.yaml | 56 ++++++++++++ .../examples/kube-lego-usage-helmfile.yaml | 23 +++++ .../examples/kube-lego-usage-ingress.yaml | 20 +++++ .../examples/kube-lego-usage-values.yaml | 14 +++ .../nginx-ingress-usage-helmfile.yaml | 13 +++ .../tls-management/kube-lego-lets-encrypt.md | 62 ++++++++++++- content/secrets-management/aws-kms.md | 8 +- content/tools/helm.md | 11 ++- 34 files changed, 452 insertions(+), 50 deletions(-) rename content/geodesic/module/{usage => }/examples/Dockerfile (100%) rename content/geodesic/module/{usage => }/examples/assume-role.txt (100%) rename content/geodesic/module/{usage => }/examples/aws-kops-backend.tf (100%) rename content/geodesic/module/{usage => }/examples/exit-geodesic-shell.txt (100%) rename content/geodesic/module/{usage => }/examples/kops-create.txt (100%) rename content/geodesic/module/{usage => }/examples/kops-update-cluster-initial.txt (100%) rename content/geodesic/module/{usage => }/examples/start-geodesic-shell.txt (100%) rename content/geodesic/module/{usage => }/examples/terraform-apply-kops-state-backend.txt (100%) rename content/geodesic/module/{usage => }/examples/terraform-apply-tfstate-backend.txt (100%) rename content/geodesic/module/{usage => }/examples/tfstate-backend.tf (100%) rename content/geodesic/module/{usage/_index.md => module-usage.md} (96%) rename content/geodesic/module/{usage => }/with-kops.md (78%) rename content/geodesic/module/{usage => }/with-terraform.md (92%) create mode 100644 content/glossary/e2e.md create mode 100644 content/glossary/helm-chart.md create mode 100644 content/glossary/helm.md create mode 100644 content/glossary/iam.md create mode 100644 content/kubernetes-backing-services/iam/examples/kube2iam-helmfile.yaml create mode 100644 content/kubernetes-backing-services/iam/examples/kube2iam-usage-deployment.yaml create mode 100644 content/kubernetes-backing-services/iam/examples/kube2iam-usage-helmfile.yaml create mode 100644 content/kubernetes-backing-services/iam/examples/kube2iam-usage-values.yaml create mode 100644 content/kubernetes-backing-services/tls-management/examples/kube-lego-helmfile.yaml create mode 100644 content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-helmfile.yaml create mode 100644 content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-ingress.yaml create mode 100644 content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-values.yaml create mode 100644 content/kubernetes-backing-services/tls-management/examples/nginx-ingress-usage-helmfile.yaml diff --git a/content/geodesic/module/_index.md b/content/geodesic/module/_index.md index e0abc01bf..247d1093c 100644 --- a/content/geodesic/module/_index.md +++ b/content/geodesic/module/_index.md @@ -1,6 +1,6 @@ --- title: "Geodesic Module" -description: "" +description: "Geodesic modules are Git repositories that extend the Geodesic base docker image and contain all Infrastructure as Code." --- {{% dialog type="info" icon="fa fa-book" title="Read More" %}} ⇠ Select one of these pages to learn more about the topic. diff --git a/content/geodesic/module/usage/examples/Dockerfile b/content/geodesic/module/examples/Dockerfile similarity index 100% rename from content/geodesic/module/usage/examples/Dockerfile rename to content/geodesic/module/examples/Dockerfile diff --git a/content/geodesic/module/usage/examples/assume-role.txt b/content/geodesic/module/examples/assume-role.txt similarity index 100% rename from content/geodesic/module/usage/examples/assume-role.txt rename to content/geodesic/module/examples/assume-role.txt diff --git a/content/geodesic/module/usage/examples/aws-kops-backend.tf b/content/geodesic/module/examples/aws-kops-backend.tf similarity index 100% rename from content/geodesic/module/usage/examples/aws-kops-backend.tf rename to content/geodesic/module/examples/aws-kops-backend.tf diff --git a/content/geodesic/module/usage/examples/exit-geodesic-shell.txt b/content/geodesic/module/examples/exit-geodesic-shell.txt similarity index 100% rename from content/geodesic/module/usage/examples/exit-geodesic-shell.txt rename to content/geodesic/module/examples/exit-geodesic-shell.txt diff --git a/content/geodesic/module/usage/examples/kops-create.txt b/content/geodesic/module/examples/kops-create.txt similarity index 100% rename from content/geodesic/module/usage/examples/kops-create.txt rename to content/geodesic/module/examples/kops-create.txt diff --git a/content/geodesic/module/usage/examples/kops-update-cluster-initial.txt b/content/geodesic/module/examples/kops-update-cluster-initial.txt similarity index 100% rename from content/geodesic/module/usage/examples/kops-update-cluster-initial.txt rename to content/geodesic/module/examples/kops-update-cluster-initial.txt diff --git a/content/geodesic/module/usage/examples/start-geodesic-shell.txt b/content/geodesic/module/examples/start-geodesic-shell.txt similarity index 100% rename from content/geodesic/module/usage/examples/start-geodesic-shell.txt rename to content/geodesic/module/examples/start-geodesic-shell.txt diff --git a/content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt b/content/geodesic/module/examples/terraform-apply-kops-state-backend.txt similarity index 100% rename from content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt rename to content/geodesic/module/examples/terraform-apply-kops-state-backend.txt diff --git a/content/geodesic/module/usage/examples/terraform-apply-tfstate-backend.txt b/content/geodesic/module/examples/terraform-apply-tfstate-backend.txt similarity index 100% rename from content/geodesic/module/usage/examples/terraform-apply-tfstate-backend.txt rename to content/geodesic/module/examples/terraform-apply-tfstate-backend.txt diff --git a/content/geodesic/module/usage/examples/tfstate-backend.tf b/content/geodesic/module/examples/tfstate-backend.tf similarity index 100% rename from content/geodesic/module/usage/examples/tfstate-backend.tf rename to content/geodesic/module/examples/tfstate-backend.tf diff --git a/content/geodesic/module/usage/_index.md b/content/geodesic/module/module-usage.md similarity index 96% rename from content/geodesic/module/usage/_index.md rename to content/geodesic/module/module-usage.md index 2eeedbbe5..2287b5cc1 100644 --- a/content/geodesic/module/usage/_index.md +++ b/content/geodesic/module/module-usage.md @@ -10,7 +10,7 @@ description: "" All examples are based on use cases provided in [Agenda]({{< relref "learn-by-example/agenda.md" >}}) {{% /dialog %}} -# Run shell +# Start the Geodesic Shell A Geodesic Module is docker container that extends Geodesic and used as a shell. @@ -39,7 +39,7 @@ Run the wrapper script to start a new shell. The first thing you will need to do ```shell > staging.example.com # Mounting /home/goruha into container -# Starting new staging.example.com session from cloudposse/staging.example.com:dev +# Starting new staging.example.com session from cloudposse/staging.example.com:dev # Exposing port 48934 * Started EC2 metadata service at http://169.254.169.254/latest _ _ _ @@ -63,6 +63,5 @@ Enter token for arn:aws:iam::xxxxxxx:mfa/goruha: 365322 * Assumed role arn:aws:iam::xxxxxxx:role/OrganizationAccountAccessRole ⧉ staging example > ✅ (example-staging-admin) ~ ➤ - ``` {{% /dialog %}} diff --git a/content/geodesic/module/usage/with-kops.md b/content/geodesic/module/with-kops.md similarity index 78% rename from content/geodesic/module/usage/with-kops.md rename to content/geodesic/module/with-kops.md index 37178b34a..940f95802 100644 --- a/content/geodesic/module/usage/with-kops.md +++ b/content/geodesic/module/with-kops.md @@ -1,15 +1,15 @@ --- -title: "Using Geodesic Module with Kops" -description: "" +title: "Using Geodesic with Kops" +description: "Learn how to provision kops clusters using Geodesic Modules." --- {{% dialog type="warning" icon="fa-info-circle" title="Prerequisites" %}} -This assumes you've followed the [Geodesic Module Usage with Terraform]({{< relref "geodesic/module/usage/with-terraform.md" >}}) guide which covers all the scaffolding necessary to get started. +This assumes you've followed the [Geodesic Module Usage with Terraform]({{< relref "geodesic/module/with-terraform.md" >}}) guide which covers all the scaffolding necessary to get started. {{% /dialog %}} Geodesic uses [kops]({{< relref "tools/kops.md" >}}) to manage kubernetes clusters. -# Create a cluster +# Create a Cluster Provisioning a `kops` cluster takes three steps: @@ -37,7 +37,7 @@ Replace with values to suit your specific project. Note, the variables correspon ### Rebuild the module -[Rebuild](/geodesic/module/usage/) the module +[Rebuild](/geodesic/module/) the module ```shell > make build ``` @@ -46,7 +46,7 @@ Replace with values to suit your specific project. Note, the variables correspon Create a file in `./conf/aws-kops-backend/main.tf` with following content -{{% include-code-block title="./conf/aws-kops-backend/main.tf" file="geodesic/module/usage/examples/aws-kops-backend.tf" language="hcl" %}} +{{% include-code-block title="./conf/aws-kops-backend/main.tf" file="geodesic/module/examples/aws-kops-backend.tf" language="hcl" %}} ### Start the shell @@ -55,7 +55,7 @@ Run the Geodesic shell. The wrapper script is installed in `/usr/local/bin/$CLUS sh-3.2$ $CLUSTER_NAME ``` -{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/usage/examples/start-geodesic-shell.txt" %}} +{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/examples/start-geodesic-shell.txt" %}} ### Authorize on AWS Assume role by running @@ -63,7 +63,7 @@ Assume role by running assume-role ``` -{{% include-code-block title="Assume role" file="geodesic/module/usage/examples/assume-role.txt" %}} +{{% include-code-block title="Assume role" file="geodesic/module/examples/assume-role.txt" %}} ### Provision aws-kops-backend @@ -76,7 +76,7 @@ terraform apply From the Terraform outputs, copy the `zone_name` and `bucket_name` into the ENV vars `KOPS_DNS_ZONE` and `KOPS_STATE_STORE` in the `Dockerfile`. -{{% include-code-block title="terraform apply" file="geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt" %}} +{{% include-code-block title="terraform apply" file="geodesic/module/examples/terraform-apply-kops-state-backend.txt" %}} In the example the bucket name is `bucket_name = example-staging-kops-state` and `zone_name = us-west-2.staging.example.com`. The public and private SSH keys are created and stored automatically in the encrypted S3 bucket. @@ -100,7 +100,7 @@ RUN s3 fstab '${TF_BUCKET}' '/' '/secrets/tf' Replace with values to suit your specific project. ### Rebuild module -[Rebuild](/geodesic/module/usage/) the module +[Rebuild](/geodesic/module/) the module ```shell > make build ``` @@ -119,7 +119,7 @@ The geodesic module can overload the template if a different architecture is des Add to the module `Dockerfile` environment variables -{{% include-code-block title="Dockerfile" file="content/geodesic/module/usage/examples/Dockerfile" %}} +{{% include-code-block title="Dockerfile" file="content/geodesic/module/examples/Dockerfile" %}} You might want to adjust these settings: @@ -133,7 +133,7 @@ Note, `NODE_MIN_SIZE` must be equal to or greater than the number of availabilit ### Rebuild the module -[Rebuild](/geodesic/module/usage/) the module +[Rebuild](/geodesic/module/) the module ```shell > make build ``` @@ -150,18 +150,18 @@ Run the Geodesic shell. > assume-role ``` -{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/usage/examples/start-geodesic-shell.txt" %}} -{{% include-code-block title="Assume role" file="geodesic/module/usage/examples/assume-role.txt" %}} +{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/examples/start-geodesic-shell.txt" %}} +{{% include-code-block title="Assume role" file="geodesic/module/examples/assume-role.txt" %}} ### Create the cluster Run `kops create -f /conf/kops/manifest.yaml` to create the cluster (this will just create the cluster state and store it in the S3 bucket, but not the AWS resources for the cluster). -{{% include-code-block title="Example" file="content/geodesic/module/usage/examples/kops-create.txt" %}} +{{% include-code-block title="Example" file="content/geodesic/module/examples/kops-create.txt" %}} ### Add ssh keys -To add [ssh keys generated previously]({{< relref "geodesic/module/usage/with-kops.md#provision-aws-kops-backend" >}}), run the following command to mount the s3 bucket containing the SSH keys and register the SSH public key with the cluster. +To add [ssh keys generated previously]({{< relref "geodesic/module/with-kops.md#provision-aws-kops-backend" >}}), run the following command to mount the s3 bucket containing the SSH keys and register the SSH public key with the cluster. {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} ``` @@ -183,7 +183,7 @@ Run the following to provision the AWS resources for the cluster. The `--yes` wi kops update cluster --name us-west-2.staging.example.com --yes ``` -{{% include-code-block title="kops update cluster --name us-west-2.staging.example.com --yes" file="geodesic/module/usage/examples/kops-update-cluster-initial.txt" %}} +{{% include-code-block title="kops update cluster --name us-west-2.staging.example.com --yes" file="geodesic/module/examples/kops-update-cluster-initial.txt" %}} All done. At this point, the `kops` cluster is now up and running (though it might take 5-10 minutes before all nodes come online). @@ -195,6 +195,30 @@ For more information, check out the following links: * https://icicimov.github.io/blog/virtualization/Kubernetes-Cluster-in-AWS-with-Kops {{% /dialog %}} + +# Update a Cluster + +Run `kops replace -f /conf/kops/manifest.yaml` to update the cluster. This will just update the cluster state in the S3 bucket, but not modify any of the underlying AWS resources for the cluster. + +## Apply the Updates + +Run the following command to update the AWS resources for the cluster. The `--yes` will apply the changes non-interactively. + +``` +kops update cluster --name us-west-2.staging.example.com --yes +``` + +All done. At this point, the `kops` cluster is now updated and running. + +# Configure `kubectl` + +When you run into the Geodesic module shell you need to export the `kubecfg` which provides the TLS client certificates necessary for `kubectl` to authenticate with the cluster. + +``` +✅ (example-staging-admin) ~ ➤ kops export kubecfg $KOPS_CLUSTER_NAME +kops has set your kubectl context to us-west-2.staging.example.com +``` + # Provision Platform Backing Services We provide a number of well-tested [Terraform Modules]({{< relref "terraform-modules/overview.md" >}}) to provision essential AWS resources needed by Helm Charts like [external-dns](/kubernetes-backing-services/external-dns/) and [chart-repo]({{}}). See our [Terraform modules for Kubernetes (Kops)](/terraform-modules/kops-kubernetes). diff --git a/content/geodesic/module/usage/with-terraform.md b/content/geodesic/module/with-terraform.md similarity index 92% rename from content/geodesic/module/usage/with-terraform.md rename to content/geodesic/module/with-terraform.md index ea2f2b89e..f53163617 100644 --- a/content/geodesic/module/usage/with-terraform.md +++ b/content/geodesic/module/with-terraform.md @@ -1,10 +1,10 @@ --- -title: "Using Geodesic Modules with Terraform" +title: "Using Geodesic with Terraform" description: "Learn how to use a Geodesic Module to manage resources using Terraform" weight: -1 --- {{% dialog type="warning" icon="fa fa-exclamation-circle" title="Prerequisites" %}} -Make sure you have [created a Geodesic Module](/geodesic/module/usage/) before continuing with these steps. +Make sure you have [created a Geodesic Module](/geodesic/module/) before continuing with these steps. {{% /dialog %}} {{% dialog type="important" icon="fa fa-exclamation-triangle" title="Important" %}} @@ -32,7 +32,7 @@ Replace with values to suit your specific project. ## Rebuild the Module -[Rebuild](/geodesic/module/usage/) the module +[Rebuild](/geodesic/module/) the module ```shell sh-3.2$ make build ``` @@ -41,7 +41,7 @@ sh-3.2$ make build Create a file in `./conf/tfstate-backend/main.tf` with following content -{{% include-code-block title="./conf/tfstate-backend/main.tf" file="geodesic/module/usage/examples/tfstate-backend.tf" language="hcl" %}} +{{% include-code-block title="./conf/tfstate-backend/main.tf" file="geodesic/module/examples/tfstate-backend.tf" language="hcl" %}} ## Start the Geodesic Shell @@ -50,7 +50,7 @@ Run the Geodesic Module shell. > $CLUSTER_NAME ``` -{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/usage/examples/start-geodesic-shell.txt" %}} +{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/examples/start-geodesic-shell.txt" %}} ## Log into AWS @@ -59,7 +59,7 @@ Assume role by running assume-role ``` -{{% include-code-block title="Assume role" file="geodesic/module/usage/examples/assume-role.txt" %}} +{{% include-code-block title="Assume role" file="geodesic/module/examples/assume-role.txt" %}} ## Save terraform state to local @@ -87,7 +87,7 @@ terraform apply When `terraform apply` completes, it output the value of the terraform state bucket and DynamoDB table. Take note of these values because we will need them in the following steps. -{{% include-code-block title="terraform apply" file="geodesic/module/usage/examples/terraform-apply-tfstate-backend.txt" %}} +{{% include-code-block title="terraform apply" file="geodesic/module/examples/terraform-apply-tfstate-backend.txt" %}} In the example the bucket name is `example-staging-terraform-state` and dynamo DB table `example-staging-terraform-state-lock`. @@ -123,7 +123,7 @@ terraform apply Exit from the shell by running `exit` twice -{{% include-code-block title="Exit the shell" file="geodesic/module/usage/examples/exit-geodesic-shell.txt" language="" %}} +{{% include-code-block title="Exit the shell" file="geodesic/module/examples/exit-geodesic-shell.txt" language="" %}} ## Config environment variables @@ -140,7 +140,7 @@ Update the values based on the outputs from the previous step. ## Rebuild module -[Rebuild](/geodesic/module/usage/) the module. +[Rebuild](/geodesic/module/) the module. ```shell > make build @@ -183,7 +183,7 @@ If `$CLUSTER_NAME=staging.example.com` simply run the command `staging.example.c ```bash assume-role ``` -{{% include-code-block title="Assume role" file="geodesic/module/usage/examples/assume-role.txt" %}} +{{% include-code-block title="Assume role" file="geodesic/module/examples/assume-role.txt" %}} ## Provision terraform module diff --git a/content/glossary/e2e.md b/content/glossary/e2e.md new file mode 100644 index 000000000..aa2457067 --- /dev/null +++ b/content/glossary/e2e.md @@ -0,0 +1,8 @@ +--- +title: "End-to-end (e2e)" +description: "The term *end-to-end* encompasses an entire workflow from start to finish." +terms: +- e2e +- end to end +- end-to-end +--- diff --git a/content/glossary/helm-chart.md b/content/glossary/helm-chart.md new file mode 100644 index 000000000..e334febec --- /dev/null +++ b/content/glossary/helm-chart.md @@ -0,0 +1,13 @@ +--- +title: "Helm Chart" +description: "A *Helm Chart* is a package that defines all the kubernetes resources necessary for deploying an application to kubernetes." +terms: +- helm chart +- helm charts +- chart +- charts +tags: +- helm +- Helmfile +- k8s +--- diff --git a/content/glossary/helm.md b/content/glossary/helm.md new file mode 100644 index 000000000..1d5c607da --- /dev/null +++ b/content/glossary/helm.md @@ -0,0 +1,10 @@ +--- +title: "Helm" +description: "Helm is one of the predominant package managers for kubernetes which is used for installing applications on the cluster." +terms: +- helm +tags: +- k8s +- helm charts +- helmfile +--- diff --git a/content/glossary/iam.md b/content/glossary/iam.md new file mode 100644 index 000000000..15f40f4ae --- /dev/null +++ b/content/glossary/iam.md @@ -0,0 +1,11 @@ +--- +title: "Identity Access Management (IAM)" +description: "Amazon's IAM is a service that helps you securely control access to AWS resources." +terms: +- IAM +- Identity Access Management +tags: +- AWS +- ACL +- security +--- diff --git a/content/glossary/mfa.md b/content/glossary/mfa.md index 547d1c3d1..134aa5a19 100644 --- a/content/glossary/mfa.md +++ b/content/glossary/mfa.md @@ -3,6 +3,7 @@ title: "Multi-Factor Authentication (MFA)" description: 'Multifactor authentication is a security "Best Practice" of requiring more than one method to verify access credentials during authentication' terms: - MFA +- MFA Token - Multi-Factor Authentication - Multi Factor Authentication - 2FA diff --git a/content/kubernetes-backing-services/_index.md b/content/kubernetes-backing-services/_index.md index eb70d6f5f..799381579 100644 --- a/content/kubernetes-backing-services/_index.md +++ b/content/kubernetes-backing-services/_index.md @@ -3,6 +3,13 @@ title: "Kubernetes Backing Services" description: "" icon: "fa fa-database" --- -We provide a number of [Terraform Modules]({{< relref "terraform-modules/overview.md" >}}) to provision AWS resources needed by Kubernetes backing service like [external-dns](/kubernetes-backing-services/external-dns/) and [chart-repo]({{}}). + +{{% dialog type="warning" icon="fa-info-circle" title="Prerequisites" %}} +This assumes you've followed the [Helm server side install]({{< relref "tools/helm.md" >}}) guide which covers all the scaffolding necessary to get started. +{{% /dialog %}} + + + +We provide a number of [Terraform Modules]({{< relref "terraform-modules/overview.md" >}}) to provision AWS resources needed by Kubernetes backing service like [external-dns](/kubernetes-backing-services/external-dns/) and [chart-repo]({{}}). See our [Terraform modules for Kubernetes (Kops)](/terraform-modules/kops-kubernetes) for modules specific to kops. diff --git a/content/kubernetes-backing-services/iam/examples/kube2iam-helmfile.yaml b/content/kubernetes-backing-services/iam/examples/kube2iam-helmfile.yaml new file mode 100644 index 000000000..8d3b345b7 --- /dev/null +++ b/content/kubernetes-backing-services/iam/examples/kube2iam-helmfile.yaml @@ -0,0 +1,36 @@ +repositories: +- name: "stable" + url: "https://kubernetes-charts.storage.googleapis.com" + +releases: +- name: "iam" + namespace: "kube-system" + labels: + chart: "kube2iam" + component: "iam" + namespace: "kube-system" + vendor: "jtblin" + default: "true" + chart: "stable/kube2iam" + version: "0.8.5" + set: + - name: "tolerations[0].key" + value: "node-role.kubernetes.io/master" + - name: "tolerations[0].effect" + value: "NoSchedule" + - name: "aws.region" + value: 'us-west-2' + - name: "extraArgs.auto-discover-base-arn" + value: "true" + - name: "host.iptables" + value: "true" + - name: "host.interface" + value: "cali+" + - name: "resources.limits.cpu" + value: "200m" + - name: "resources.limits.memory" + value: "256Mi" + - name: "resources.requests.cpu" + value: "50m" + - name: "resources.requests.memory" + value: "128Mi" diff --git a/content/kubernetes-backing-services/iam/examples/kube2iam-usage-deployment.yaml b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-deployment.yaml new file mode 100644 index 000000000..908c5f4a3 --- /dev/null +++ b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-deployment.yaml @@ -0,0 +1,18 @@ +apiVersion: extensions/v1beta1 +kind: Deployment +metadata: + name: chartmuseum-deployment +spec: + replicas: 3 + template: + metadata: + annotations: + iam.amazonaws.com/role: s3-access-role + labels: + app: chartmuseum + spec: + containers: + - name: chartmuseum + image: chartmuseum/chartmuseum:v0.5.2 + ports: + - containerPort: 80 diff --git a/content/kubernetes-backing-services/iam/examples/kube2iam-usage-helmfile.yaml b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-helmfile.yaml new file mode 100644 index 000000000..679b74150 --- /dev/null +++ b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-helmfile.yaml @@ -0,0 +1,11 @@ +repositories: +- name: stable + url: https://kubernetes-charts.storage.googleapis.com + +releases: +- name: charts + chart: stable/chartmuseum + version: 1.3.1 + set: + - name: replica.annotations.iam.amazonaws\.com/role + value: s3-access-role diff --git a/content/kubernetes-backing-services/iam/examples/kube2iam-usage-values.yaml b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-values.yaml new file mode 100644 index 000000000..f3609ee6f --- /dev/null +++ b/content/kubernetes-backing-services/iam/examples/kube2iam-usage-values.yaml @@ -0,0 +1,3 @@ +replica: + annotations: + iam.amazonaws.com/role: s3-access-role diff --git a/content/kubernetes-backing-services/iam/kube2iam.md b/content/kubernetes-backing-services/iam/kube2iam.md index ea22e7823..b5f942287 100644 --- a/content/kubernetes-backing-services/iam/kube2iam.md +++ b/content/kubernetes-backing-services/iam/kube2iam.md @@ -1,22 +1,90 @@ --- title: "Kube2IAM" description: "" -draft: true --- -# Synopsis - -Explain what it does # Dependencies +None + +# Install + +## Enable Assumed Roles + +{{% dialog type="important" icon="fa fa-exclamation-triangle" title="Important" %}} +By default, the kops manifest that ships with Geodesic is configured to permit nodes to assume roles. +So you can continue to [next step]({{< relref "#kops-integration" >}}) +{{% /dialog %}} + +All Kubernetes nodes instance profile should have permissions to assume role. + +To do this, kops manifest should define following `additionalPolicies`. By default, we include this in the [`manifest.yaml`](https://github.com/cloudposse/geodesic/blob/master/rootfs/templates/kops/default.yaml#L6-L17) that ships with geodesic. + +{{% dialog type="code-block" icon="fa fa-code" title="manifest.yaml" %}} +```yaml +apiVersion: kops/v1alpha2 +kind: Cluster +metadata: + name: us-west-2.staging.example.com +spec: + additionalPolicies: + nodes: | + [ + { + "Sid": "assumeClusterRole", + "Action": [ + "sts:AssumeRole" + ], + "Effect": "Allow", + "Resource": ["*"] + } + ] +``` +{{% /dialog %}} + +Follow the instructions to [apply changes to the kops cluster]({{< relref "geodesic/module/with-kops.md#update-a-cluster" >}}) + +## Kops Integration + +Now to leverage IAM Roles with your `kops` cluster, you'll need to install `kube2iam`. There are a number of ways to go about this, but we recommend to use our Master Helmfile that ships with Geodesic. + +### Install with Master Helmfile + +{{% dialog type="code-block" icon="fa fa-code" title="Install `kube-lego`" %}} +``` +helmfile -f /conf/kops/helmfile.yaml --selector chart=kube2iam sync +``` +{{% /dialog %}} + +This service depends on the following environment variables: + +* `AWS_REGION` - AWS region + +Environment variables can be specified in Geodesic Module's `Dockerfile` or using [Chamber]({{< relref "tools/chamber.md" >}}) storage. + +### Install with Custom Helmfile + +Add to your [Kubernetes Backing Services](/kubernetes-backing-services) Helmfile this code snippet. + +{{% include-code-block title="helmfile.yaml" file="kubernetes-backing-services/iam/examples/kube2iam-helmfile.yaml" language="yaml" %}} + +Then run [`helmfile sync`]({{< relref "tools/helmfile.md" >}}) to install. + +# Usage + +Add an annotation login `iam.amazonaws.com/role: "some-aws-role"` to the kubernetes resource (e.g. `Deployment`, `CronJob`, `ReplicaSet`, `Pod`, etc). Replace `some-aws-role` with an IAM role that you've previously provisioned. + +We recommend provisioning all IAM roles using terraform modules like this one (`terraform-aws-kops-external-dns`)[https://github.com/cloudposse/terraform-aws-kops-external-dns] for provisioning IAM roles to access Route53. -Link to kops manifest with code snippet here. +Here are some examples: +{{% include-code-block title="ingress.yaml" file="kubernetes-backing-services/iam/examples/kube2iam-usage-deployment.yaml" language="yaml" %}} -# Example +{{% include-code-block title="values.yaml" file="kubernetes-backing-services/iam/examples/kube2iam-usage-values.yaml" language="yaml" %}} -Give `helmfile` stub / example +{{% include-code-block title="helmfile.yaml" file="kubernetes-backing-services/iam/examples/kube2iam-usage-helmfile.yaml" language="yaml" %}} -# Usage Example +{{% dialog type="info" icon="fa-info-circle" title="Note" %}} +There is no unified specification for the structure of helm chart values. Different charts may have very different structures to values. The only way to know for sure what is supported is to refer to the chart manifests. Additionally, there's no schema validation for `values.yaml`, so specifying an incorrect structure will not raise any alarms. -Example annotations -Link to charts that do it +Provided examples are based on the `stable/chartmuseum` chart https://github.com/kubernetes/charts/blob/master/stable/chartmuseum +{{% /dialog %}} diff --git a/content/kubernetes-backing-services/ingress/nginx-ingress-controller.md b/content/kubernetes-backing-services/ingress/nginx-ingress-controller.md index cca26368e..0ae4d0644 100644 --- a/content/kubernetes-backing-services/ingress/nginx-ingress-controller.md +++ b/content/kubernetes-backing-services/ingress/nginx-ingress-controller.md @@ -14,7 +14,7 @@ to use Master Helmfile. Run following command ``` -helmfile -f /conf/kops/helmfile.yaml --selector namespace=kube-system,chart=ingress sync +helmfile -f /conf/kops/helmfile.yaml --selector namespace=kube-system,chart=nginx-ingress sync ``` This environment variables can be useful for configure: diff --git a/content/kubernetes-backing-services/tls-management/examples/kube-lego-helmfile.yaml b/content/kubernetes-backing-services/tls-management/examples/kube-lego-helmfile.yaml new file mode 100644 index 000000000..71498df31 --- /dev/null +++ b/content/kubernetes-backing-services/tls-management/examples/kube-lego-helmfile.yaml @@ -0,0 +1,56 @@ +repositories: +- name: cloudposse-incubator + url: https://charts.cloudposse.com/incubator/ + +releases: +- name: tls + namespace: kube-system + labels: + job: kube-system + chart: cloudposse-incubator/kube-lego + version: 0.1.2 + set: + ### Optional: KUBE_LEGO_REPLICA_COUNT; e.g. 1 + - name: "replicaCount" + value: '1' + + ### Optional: KUBE_LEGO_DEBUG; e.g. false + - name: "debug" + value: 'false' + + ## Image + - name: "image.repository" + value: "jetstack/kube-lego" + + ### Optional: KUBE_LEGO_IMAGE_TAG; e.g. 0.1.2 + - name: "image.tag" + value: '0.1.5' + + - name: "image.pullPolicy" + value: "IfNotPresent" + + ## Lego Settings + ### Required: KUBE_LEGO_EMAIL; e.g. ops@cloudposse.org + - name: "lego.email" + value: '' + + ### Optional: KUBE_LEGO_PROD; e.g. true + - name: "lego.prod" + value: 'true' + + ## Pod Settings + - name: "pod.internalPort" + value: "8080" + + ## Resources + - name: "resources.limits.cpu" + value: "200m" + + - name: "resources.limits.memory" + value: "256Mi" + + - name: "resources.requests.cpu" + value: "50m" + + - name: "resources.requests.memory" + value: "128Mi" diff --git a/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-helmfile.yaml b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-helmfile.yaml new file mode 100644 index 000000000..4e7ed5e8c --- /dev/null +++ b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-helmfile.yaml @@ -0,0 +1,23 @@ +repositories: +- name: stable + url: https://kubernetes-charts.storage.googleapis.com + +releases: +- name: charts + chart: stable/chartmuseum + version: 1.3.1 + set: + - name: ingress.enabled + value: true + - name: ingress.annotations.kubernetes\.io/ingress\.class + value: nginx + - name: ingress.annotations.kubernetes\.io/tls-acme + value: true + - name: ingress.hosts.example\.com[0] + value: /charts + - name: ingress.hosts.example\.com[1] + value: /index.yaml + - name: ingress.tls[0].secretName + value: chartmuseum-server-tls + - name: ingress.tls[0].hosts[0] + value: example.com diff --git a/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-ingress.yaml b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-ingress.yaml new file mode 100644 index 000000000..b23180525 --- /dev/null +++ b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-ingress.yaml @@ -0,0 +1,20 @@ +apiVersion: extensions/v1beta1 +kind: Ingress +metadata: + name: chartmuseum + annotations: + kubernetes.io/tls-acme: "true" +spec: + rules: + - host: example.com + http: + paths: + - path: / + backend: + serviceName: chartmuseum-service + servicePort: 80 + tls: + - secretName: chartmuseum-tls + hosts: + - example.com + - www.example.com diff --git a/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-values.yaml b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-values.yaml new file mode 100644 index 000000000..9bca73ad0 --- /dev/null +++ b/content/kubernetes-backing-services/tls-management/examples/kube-lego-usage-values.yaml @@ -0,0 +1,14 @@ +## Ingress for load balancer +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + kubernetes.io/tls-acme: "true" + hosts: + example.com: + - /charts + - /index.yaml + tls: + - secretName: chartmuseum-server-tls + hosts: + - example.com diff --git a/content/kubernetes-backing-services/tls-management/examples/nginx-ingress-usage-helmfile.yaml b/content/kubernetes-backing-services/tls-management/examples/nginx-ingress-usage-helmfile.yaml new file mode 100644 index 000000000..e8f84f4f8 --- /dev/null +++ b/content/kubernetes-backing-services/tls-management/examples/nginx-ingress-usage-helmfile.yaml @@ -0,0 +1,13 @@ +repositories: +- name: stable + url: https://kubernetes-charts.storage.googleapis.com + +releases: +- name: charts + chart: stable/chartmuseum + version: 1.3.1 + set: + - name: ingress.enabled + value: true + - name: ingress.hosts.example\.com[0] + value: / diff --git a/content/kubernetes-backing-services/tls-management/kube-lego-lets-encrypt.md b/content/kubernetes-backing-services/tls-management/kube-lego-lets-encrypt.md index 41218d604..a0839dc7d 100644 --- a/content/kubernetes-backing-services/tls-management/kube-lego-lets-encrypt.md +++ b/content/kubernetes-backing-services/tls-management/kube-lego-lets-encrypt.md @@ -1,5 +1,65 @@ --- title: "Kube Lego (Let's Encrypt)" description: "" -draft: true --- + +# Dependencies + +The way `kube-lego` works is by looking for annotations on `Ingress` and `Service` resources. Thus to use `kube-lego`, it's necessary to first install an [ingress controller]({{< relref "kubernetes-backing-services/ingress/_index.md" >}}). + +Out of the box, `kube-lego` support 2 types of [ingress controllers](https://github.com/jetstack/kube-lego#ingress-controllers) +* GCE Load Balancers +* Nginx Ingress Controller + +# Install + +You can install `kube-lego` in a few different ways, but we recomend to use the [Master Helmfile](https://github.com/cloudposse/geodesic/blob/master/rootfs/conf/kops/helmfile.yaml). + +## Install with Master Helmfile + +1. Set the `KUBE_LEGO_EMAIL` secret with chamber +2. Run then install `kube-lego` using `helmfile sync`. + +{{% dialog type="code-block" icon="fa fa-code" title="Install kube-lego" %}} +``` +chamber write kops KUBE_LEGO_EMAIL devops@example.com +chamber exec kops -- helmfile -f /conf/kops/helmfile.yaml --selector namespace=kube-system,chart=kube-lego sync +``` +{{% /dialog %}} + +These are some of the environment variables you may want to configure: + +* `KUBE_LEGO_REPLICA_COUNT` - Count of `kube-lego` pods +* `KUBE_LEGO_IMAGE_TAG` - Version of [`kube-lego` image](https://hub.docker.com/r/jetstack/kube-lego/) +* `KUBE_LEGO_DEBUG` - Boolean to enabled debug mode. Defaults `false` +* `KUBE_LEGO_PROD` - Boolean to enabled prod/stage mode. Defaults `true` + +Environment variables can be specified in the Geodesic Module's `Dockerfile` or using [Chamber]({{< relref "tools/chamber.md" >}}) storage, which is recommended for all secrets. + +## Install with Custom Helmfile + +Add to your [Kubernetes Backing Services](/kubernetes-backing-services) Helmfile this code + +{{% include-code-block title="helmfile.yaml" file="kubernetes-backing-services/tls-management/examples/kube-lego-helmfile.yaml" language="yaml" %}} + +Then follow the instructions for running [`helmfile sync`]({{< relref "tools/helmfile.md" >}}). We recommend passing the `--selector` argument so you can pinpoint a specific chart. + +# Usage + +To leverage `kube-lego`, you will need to add an annotations (e.g. `kubernetes.io/tls-acme: "true"`) to the `Ingress` resource. + +With these in place, then `kube-lego` will handle all e2e TLS certificate issueing and save the certificate from Let's Encrypt to a secret specificied by the `tls` config. + +Here are some examples: + +{{% include-code-block title="ingress.yaml" file="kubernetes-backing-services/tls-management/examples/kube-lego-usage-ingress.yaml" language="yaml" %}} + +{{% include-code-block title="values.yaml" file="kubernetes-backing-services/tls-management/examples/kube-lego-usage-values.yaml" language="yaml" %}} + +{{% include-code-block title="helmfile.yaml" file="kubernetes-backing-services/tls-management/examples/kube-lego-usage-helmfile.yaml" language="yaml" %}} + +{{% dialog type="info" icon="fa-info-circle" title="Note" %}} +There is no unified specification for helm chart values structure. Different charts may have very different structures to values. The only way to know for sure what is supported is to refer to the chart manifests. + +Provided examples are based on the `stable/chartmuseum` chart https://github.com/kubernetes/charts/blob/master/stable/chartmuseum +{{% /dialog %}} diff --git a/content/secrets-management/aws-kms.md b/content/secrets-management/aws-kms.md index 479367541..6041de00c 100644 --- a/content/secrets-management/aws-kms.md +++ b/content/secrets-management/aws-kms.md @@ -4,7 +4,7 @@ description: "Use Terraform to easily provision all KMS+SSM resources for Chambe --- {{% dialog type="warning" icon="fa-info-circle" title="Prerequisites" %}} -This assumes you've followed the [Geodesic Module Usage with Terraform]({{< relref "geodesic/module/usage/with-terraform.md" >}}) guide which covers all the scaffolding necessary to get started. +This assumes you've followed the [Geodesic Module Usage with Terraform]({{< relref "geodesic/module/with-terraform.md" >}}) guide which covers all the scaffolding necessary to get started. {{% /dialog %}} # Dependencies @@ -21,7 +21,7 @@ Create a file in `/conf/chamber/kms.tf` with following content ## Rebuild the module -[Rebuild](/geodesic/module/usage/) the module +[Rebuild](/geodesic/module/) the module ```shell > make build ``` @@ -33,11 +33,11 @@ Run the Geodesic shell followed by `assume-role` sh-3.2$ $CLUSTER_NAME ``` -{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/usage/examples/start-geodesic-shell.txt" %}} +{{% include-code-block title="Run the Geodesic Shell" file="geodesic/module/examples/start-geodesic-shell.txt" %}} Then login to AWS by running `assume-role`: -{{% include-code-block title="Assume role" file="geodesic/module/usage/examples/assume-role.txt" %}} +{{% include-code-block title="Assume role" file="geodesic/module/examples/assume-role.txt" %}} ## Provision Chamber Resources diff --git a/content/tools/helm.md b/content/tools/helm.md index f6537e25e..0a7f37155 100644 --- a/content/tools/helm.md +++ b/content/tools/helm.md @@ -1,5 +1,12 @@ --- title: Helm -description: '' -draft: true +description: 'Helm is package manager for Kubernetes.' --- + +Helm makes it easy to install `charts` (a application) on kubernetes clusters. Just like `npm` or `apt` make it easy to install NodeJS modules and Debian packages, `helm` makes it easy to deploy a a full-fledged application with all of its dependencies on kubernetes. + +# Install Tiller + +The helm `tiller` is the server-side component of Helm. It's used to cordinate with the kubernetes cluster in order to deploy resources (E.g. `Services`, `Deployments`, `StatefulSets`, etc.) + +To install the `tiller`, just run `helm init` from the Geodesic Shell after assumming-role and running `kops export kubecfg $CLUSTER_NAME`.