Document Ingress Setup (#77)

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.

content/geodesic/module/usage/_index.md → 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 %}}

content/geodesic/module/usage/with-kops.md → 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,15 +55,15 @@ 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
 ```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 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]({{<relref "helm-charts/supported-charts/chart-repo.md" >}}). See our [Terraform modules for Kubernetes (Kops)](/terraform-modules/kops-kubernetes).

content/geodesic/module/usage/with-terraform.md → 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
 

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
+---

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
+---

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
+---

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
+---

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

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]({{<relref "helm-charts/supported-charts/chart-repo.md" >}}). 
+
+{{% 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]({{<relref "helm-charts/supported-charts/chart-repo.md" >}}).
 
 See our [Terraform modules for Kubernetes (Kops)](/terraform-modules/kops-kubernetes) for modules specific to kops.

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"

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