From 612bf4519e8b23a9070d4d9b38faff1b8f919924 Mon Sep 17 00:00:00 2001 From: Igor Rodionov Date: Fri, 18 May 2018 06:01:12 +0600 Subject: [PATCH] Geodesic documentation (#60) * Geodesic documentation * Added documetation how to spin up kops cluster * Update with-kops.md * use include-code-block * Move examples to standalone snippets * fix syntax error --- content/geodesic/module/_index.md | 2 +- content/geodesic/module/usage/_index.md | 2 +- .../geodesic/module/usage/examples/Dockerfile | 0 .../module/usage/examples/assume-role.txt | 7 + .../module/usage/examples/aws-kops-backend.tf | 86 +++++++ .../module/usage/examples/kops-create.txt | 13 + .../usage/examples/start-geodesic-shell.txt | 23 ++ .../terraform-apply-kops-state-backend.txt | 0 content/geodesic/module/usage/with-kops.md | 203 ++++++++++----- .../geodesic/module/usage/with-terraform.md | 243 ++++++++---------- layouts/shortcodes/dialog.html | 2 +- static/css/custom.css | 3 +- 12 files changed, 388 insertions(+), 196 deletions(-) create mode 100644 content/geodesic/module/usage/examples/Dockerfile create mode 100644 content/geodesic/module/usage/examples/assume-role.txt create mode 100644 content/geodesic/module/usage/examples/aws-kops-backend.tf create mode 100644 content/geodesic/module/usage/examples/kops-create.txt create mode 100644 content/geodesic/module/usage/examples/start-geodesic-shell.txt create mode 100644 content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt diff --git a/content/geodesic/module/_index.md b/content/geodesic/module/_index.md index 3153b7be0..e0abc01bf 100644 --- a/content/geodesic/module/_index.md +++ b/content/geodesic/module/_index.md @@ -1,5 +1,5 @@ --- -title: "Module" +title: "Geodesic Module" description: "" --- {{% dialog type="info" icon="fa fa-book" title="Read More" %}} diff --git a/content/geodesic/module/usage/_index.md b/content/geodesic/module/usage/_index.md index be51c1a79..3dc63ad11 100644 --- a/content/geodesic/module/usage/_index.md +++ b/content/geodesic/module/usage/_index.md @@ -1,5 +1,5 @@ --- -title: "Geodesic Usage" +title: "Geodesic Module Usage" description: "" --- # Prerequisites diff --git a/content/geodesic/module/usage/examples/Dockerfile b/content/geodesic/module/usage/examples/Dockerfile new file mode 100644 index 000000000..e69de29bb diff --git a/content/geodesic/module/usage/examples/assume-role.txt b/content/geodesic/module/usage/examples/assume-role.txt new file mode 100644 index 000000000..d9f6b5df0 --- /dev/null +++ b/content/geodesic/module/usage/examples/assume-role.txt @@ -0,0 +1,7 @@ +❌ (none) tfstate-backend ➤ assume-role +Enter passphrase to unlock /conf/.awsvault/keys/: +Enter token for arn:aws:iam::xxxxxxx:mfa/goruha: 781874 +* Assumed role arn:aws:iam::xxxxxxx:role/OrganizationAccountAccessRole +-> Run 'init-terraform' to use this project + ⧉ staging example +✅ (example-staging-admin) tfstate-backend ➤ diff --git a/content/geodesic/module/usage/examples/aws-kops-backend.tf b/content/geodesic/module/usage/examples/aws-kops-backend.tf new file mode 100644 index 000000000..8888fcd2f --- /dev/null +++ b/content/geodesic/module/usage/examples/aws-kops-backend.tf @@ -0,0 +1,86 @@ +terraform { + required_version = ">= 0.11.2" + backend "s3" {} +} + +variable "aws_assume_role_arn" {} + +variable "tfstate_namespace" {} + +variable "tfstate_stage" {} + +variable "tfstate_region" {} + +variable "kops_cluster_name" {} + +variable "parent_zone_name" {} + +provider "aws" { + assume_role { + role_arn = "${var.aws_assume_role_arn}" + } +} + +module "kops_state_backend" { + source = "git::https://github.com/cloudposse/terraform-aws-kops-state-backend.git?ref=tags/0.1.3" + namespace = "${var.tfstate_namespace}" + stage = "${var.tfstate_stage}" + name = "kops-state" + parent_zone_name = "${var.parent_zone_name}" + zone_name = "$${name}.$${parent_zone_name}" + cluster_name = "${var.tfstate_region}" + region = "${var.tfstate_region}" +} + +module "ssh_key_pair" { + source = "git::https://github.com/cloudposse/terraform-aws-key-pair.git?ref=tags/0.2.3" + namespace = "${var.tfstate_namespace}" + stage = "${var.tfstate_stage}" + name = "kops-${var.tfstate_region}" + ssh_public_key_path = "/secrets/tf/ssh" + generate_ssh_key = "true" +} + +output "parent_zone_id" { + value = "${module.kops_state_backend.parent_zone_id}" +} + +output "parent_zone_name" { + value = "${module.kops_state_backend.parent_zone_name}" +} + +output "zone_id" { + value = "${module.kops_state_backend.zone_id}" +} + +output "zone_name" { + value = "${module.kops_state_backend.zone_name}" +} + +output "bucket_name" { + value = "${module.kops_state_backend.bucket_name}" +} + +output "bucket_region" { + value = "${module.kops_state_backend.bucket_region}" +} + +output "bucket_domain_name" { + value = "${module.kops_state_backend.bucket_domain_name}" +} + +output "bucket_id" { + value = "${module.kops_state_backend.bucket_id}" +} + +output "bucket_arn" { + value = "${module.kops_state_backend.bucket_arn}" +} + +output "ssh_key_name" { + value = "${module.ssh_key_pair.key_name}" +} + +output "ssh_public_key" { + value = "${module.ssh_key_pair.public_key}" +} diff --git a/content/geodesic/module/usage/examples/kops-create.txt b/content/geodesic/module/usage/examples/kops-create.txt new file mode 100644 index 000000000..bd5aa2656 --- /dev/null +++ b/content/geodesic/module/usage/examples/kops-create.txt @@ -0,0 +1,13 @@ +✅ (example-staging-admin) kops ➤ kops create -f /conf/kops/manifest.yaml + +Created cluster/us-west-2.staging.example.com +Created instancegroup/bastions +Created instancegroup/master-us-west-2a +Created instancegroup/master-us-west-2b +Created instancegroup/master-us-west-2c +Created instancegroup/nodes + +To deploy these resources, run: kops update cluster us-west-2.staging.example.com --yes + + ⧉ staging example +✅ (example-staging-admin) kops ➤ diff --git a/content/geodesic/module/usage/examples/start-geodesic-shell.txt b/content/geodesic/module/usage/examples/start-geodesic-shell.txt new file mode 100644 index 000000000..654c0af05 --- /dev/null +++ b/content/geodesic/module/usage/examples/start-geodesic-shell.txt @@ -0,0 +1,23 @@ +sh-3.2$ staging.example.com +# Mounting /home/goruha into container +# Starting new staging.example.com session from cloudposse/staging.example.com:dev +# Exposing port 41179 +* Started EC2 metadata service at http://169.254.169.254/latest + + _ _ _ + ___| |_ __ _ __ _(_)_ __ __ _ _____ ____ _ _ __ ___ _ __ | | ___ + / __| __/ _` |/ _` | | '_ \ / _` | / _ \ \/ / _` | '_ ` _ \| '_ \| |/ _ \ + \__ \ || (_| | (_| | | | | | (_| | | __/> < (_| | | | | | | |_) | | __/ + |___/\__\__,_|\__, |_|_| |_|\__, | \___/_/\_\__,_|_| |_| |_| .__/|_|\___| + |___/ |___/ |_| + + +IMPORTANT: +* Your $HOME directory has been mounted to `/localhost` +* Use `aws-vault` to manage your sessions +* Run `assume-role` to start a session + + +-> Run 'assume-role' to login to AWS + ⧉ staging example +❌ (none) ~ ➤ diff --git a/content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt b/content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt new file mode 100644 index 000000000..e69de29bb diff --git a/content/geodesic/module/usage/with-kops.md b/content/geodesic/module/usage/with-kops.md index a0509e5c4..4fb5bfca3 100644 --- a/content/geodesic/module/usage/with-kops.md +++ b/content/geodesic/module/usage/with-kops.md @@ -1,117 +1,198 @@ --- -title: "Using Geodesic with Kops" +title: "Using Geodesic Module with Kops" description: "" --- -{{% dialog type="info" icon="fa-info-circle" title="Prerequisites" %}} -This assumes you've followed the [Geodesic Quick Start]({{< relref "geodesic/module/quickstart.md" >}}) guide which covers all the scaffolding necessary to get started. +{{% 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. {{% /dialog %}} +Geodesic uses [kops]({{< relref "tools/kops.md" >}}) to manage kubernetes clusters. + # Create a cluster -Follow the [Provision a Cluster]({{< relref "geodesic/module/usage/with-kops.md" >}}) process +Provisioning a `kops` cluster takes three steps: -# Provision Platform Backing Services +1. Provision a [`terraform-aws-kops-state-backend`]({{< relref "terraform-modules/kops-kubernetes/terraform-aws-kops-state-backend.md" >}}) which consists of an S3 bucket, cluster DNS zone, and SSH keypair to access the k8s masters and nodes. +2. Update the `Dockerfile` and rebuild the Geodesic Module to generate a kops manifest file (and restart shell) +3. Launch a kops cluster from the manifest file -A number of [Terraform Modules Overview]({{< relref "terraform-modules/overview.md" >}}) provide to provision AWS resources needed by Charts like [external-dns](/kubernetes-backing-services/external-dns/) and [chart-repo]({{}}). See our [Terraform modules for Kubernetes (Kops)](/terraform-modules/kops-kubernetes). +## Provision the State Backend + +### Config environment variables + +Update the environment variables in the module's `Dockerfile`: -# Provisioning a Kops cluster +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} +``` +ENV KOPS_CLUSTER_NAME=us-west-2.staging.example.com +ENV TF_VAR_kops_cluster_name=${KOPS_CLUSTER_NAME} +ENV TF_VAR_parent_zone_name=staging.example.com +``` +{{% /dialog %}} -We create a `kops` cluster from a manifest. +Replace with values to suit your specific project. Note, the variables correspond to the outputs of the `terraform-aws-kops-state-backend` module, which follows a strict naming convention. -The manifest template is located in [`/templates/kops/default.yaml`](https://github.com/cloudposse/geodesic/blob/master/rootfs/templates/kops/default.yaml) -and is compiled by running the `build-kops-manifest` script as a `RUN` step in the `Dockerfile`. -# Synopsis +### Rebuild the module -Provisioning a `kops` cluster takes three steps: +[Rebuild](/geodesic/module/usage/) the module +```shell +> make build +``` -1. Provision a [terraform-aws-kops-state-backend]({{< relref "terraform-modules/kops-kubernetes/terraform-aws-kops-state-backend.md" >}}) which consists of an S3 bucket, cluster DNS zone, and SSH keypair to access the k8s masters and nodes. -2. Update the `Dockerfile` and rebuild/restart the `geodesic` shell to generate a kops manifest file -3. Launch a kops cluster from the manifest file +### Add kops state terraform module + +Create file in `./conf/aws-kops-backend/main.tf` with following content -# Provision the State Backend +{{% include-code-block title="./conf/aws-kops-backend/main.tf" file="content/geodesic/module/usage/examples/aws-kops-backend.tf" language="hcl" %}} -Inside the `geodesic shell, change directory to `kops` folder +### Start the shell + +Run the Geodesic shell. The wrapper script is installed in `/usr/local/bin/$CLUSTER_NAME`, so you should be able to just run something like: +```shell +sh-3.2$ $CLUSTER_NAME +``` + +{{% include-code-block title="Run the Geodesic Shell" file="content/geodesic/module/usage/examples/start-geodesic-shell.txt" %}} + +### Authorize on AWS +Assume role by running ```bash -cd /conf/kops +assume-role ``` -Run Terraform to provision the `kops` backend (S3 bucket, DNS zone, and SSH keypair) +{{% include-code-block title="Run the Geodesic Shell" file="content/geodesic/module/usage/examples/assume-role.txt" %}} + +### Provision aws-kops-backend + +Change directory to `/conf/aws-kops-backend` and run there commands to provision the `aws-kopstate-backend` backend (S3 bucket, DNS zone, and SSH keypair) ```bash init-terraform terraform plan terraform apply ``` -![Staging Cluster State](/assets/b5e88dd-joany-staging-kops-state.png) +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`. -The public and private SSH keys are created and stored automatically in the encrypted S3 bucket. -![Staging Kops SSH Keys](/assets/9d5dc1c-joany-staging-kops-state-ssh-keys.png) +{{% include-code-block title="terraform apply" file="content/geodesic/module/usage/examples/terraform-apply-kops-state-backend.txt" %}} -From the Terraform outputs, copy the `zone_name` and `bucket_name` into the ENV vars `CLUSTER_NAME` and `KOPS_STATE_STORE` in the `Dockerfile`. +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. -# Build Manifest +### Configure environment variables -The `Dockerfile` should look something like this: +Add to module `Dockerfile` environment variable -```docker -# kops config -ENV CLUSTER_NAME="us-west-2.staging.joany.net" -ENV KOPS_DNS_ZONE=${CLUSTER_NAME} -ENV KOPS_STATE_STORE="s3://cp-prod-kops-state" -ENV KOPS_STATE_STORE_REGION="us-east-1" -ENV KOPS_AVAILABILITY_ZONES="us-east-1a,us-east-1b,us-east-1c,us-east-1d,us-east-1e" -ENV KOPS_BASTION_PUBLIC_NAME="bastion" -ENV BASTION_MACHINE_TYPE="t2.medium" -ENV MASTER_MACHINE_TYPE="t2.medium" -ENV NODE_MACHINE_TYPE="t2.medium" -ENV NODE_MAX_SIZE="2" -ENV NODE_MIN_SIZE="2" +``` +# AWS Region of the S3 bucket to store cluster configuration +ENV KOPS_STATE_STORE=s3://{KOPS_STATE_BUCKET_NAME} +ENV KOPS_STATE_STORE_REGION={AWS_REGION} +ENV KOPS_DNS_ZONE={KOPS_DNS_ZONE_NAME} ``` -Exit the `geodesic` shell by typing `exit`. You might need to run it twice if you were in an assumed role. +Replace placeholders `{%}` with values specific for your project. -Rebuild the Docker image +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} ``` -make docker/build +# AWS Region of the S3 bucket to store cluster configuration +ENV KOPS_STATE_STORE=s3://example-staging-kops-state +ENV KOPS_STATE_STORE_REGION=us-west-2 +ENV KOPS_DNS_ZONE=us-west-2.staging.example.com + +## Config /etc/fstab to mount s3 bucket that containes generated ssh key +RUN s3 fstab '${TF_BUCKET}' '/' '/secrets/tf' ``` +{{% /dialog %}} -Run the `geodesic` shell again and assume role to login to AWS -```bash -staging.joany.net -assume-role +### Rebuild module +[Rebuild](/geodesic/module/usage/) the module +```shell +> make build ``` -Change directory to `kops` folder, init Terraform, and list files -```bash -cd /conf/kops -init-terraform -ls +## Configure kops manifest + +Geodesic creates a `kops` cluster from a manifest. +[Kops manifest](https://github.com/kubernetes/kops/blob/master/docs/manifests_and_customizing_via_api.md) is yaml file that describe resources that determinates Kubernetes cluster. +`Geodesic` generates the manifest from template that support placehoders with environment variables. +The manifest template (gomplate) is located in [`/templates/kops/default.yaml`](https://github.com/cloudposse/geodesic/blob/master/rootfs/templates/kops/default.yaml) +and is compiled to `/conf/kops/manifest.yaml` by running the `build-kops-manifest` script as a `RUN` step in the `Dockerfile`. + +The geodesic module can overload the template if a different architecture is desired. All of our examples will rely on our default manifest. + +### Configure environment variables + +Add to the module `Dockerfile` environment variables + +{{% include-code-block title="terraform apply" file="content/geodesic/module/usage/examples/Dockerfile" %}} + +You might want to adjust these settings: + +* `BASTION_MACHINE_TYPE` - EC2 instance type of bation node +* `MASTER_MACHINE_TYPE` - EC2 instance type of masters +* `NODE_MACHINE_TYPE` - EC2 instance type of EC2 worker nodes +* `NODE_MIN_SIZE` - minimum number of worker nodes +* `NODE_MAX_SIZE` - maximum number of worker nodes + +Note, `NODE_MIN_SIZE` must be equal to or greater than the number of availability zones. + +### Rebuild the module + +[Rebuild](/geodesic/module/usage/) the module +```shell +> make build +``` + +When manifiest configured we can apply it with kops to spin up or update the cluster + +## Launch the cluster + +### Run into the module shell + +Run the Geodesic shell. +```shell +> $CLUSTER_NAME +> assume-role ``` -You will find the rendered `kops` manifest file `/conf/kops/manifest.yaml`. +{{% include-code-block title="Run the Geodesic Shell" file="content/geodesic/module/usage/examples/assume-role.txt" %}} + +### Create the cluster -# Launch 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). -Run `kops create -f 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" %}} -{{< img src="/assets/b251e2e-kops-create.png" title="Kops Create Example" >}} +### Add ssh keys -Run the following to add the SSH public key to the cluster. +To add [ssh keys generated previously]({{< relref "geodesic/module/usage/with-kops.md#provision-aws-kops-backend" >}}) +run the following to mount s3 bucket with SSH keys and add the SSH public key to the cluster. + +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} ``` -kops create secret sshpublickey admin -i /secrets/tf/ssh/joany-staging-kops-us-west-2.pub \ - --name us-west-2.staging.joany.net +# Mount all S3 filesystems +mount -a + +# Import SSH public key +kops create secret sshpublickey admin \ + -i /secrets/tf/ssh/example-staging-kops-us-west-2.pub \ + --name us-west-2.staging.example.com ``` +{{% /dialog %}} + +### Provision the cluster Run the following to provision the AWS resources for the cluster. ``` -kops update cluster --name us-west-2.staging.joany.net --yes +kops update cluster --name us-west-2.staging.example.com --yes ``` -{{< img src="/assets/944178e-kops-update-cluster.png" title="Kops Update Cluster Example" >}} +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} + +{{% /dialog %}} All done. The `kops` cluster is now up and running. @@ -122,3 +203,7 @@ For more information, check out the following links: * https://github.com/kubernetes/kops/blob/master/docs/security.md * https://icicimov.github.io/blog/virtualization/Kubernetes-Cluster-in-AWS-with-Kops {{% /dialog %}} + +# Provision Platform Backing Services + +A number of [Terraform Modules Overview]({{< relref "terraform-modules/overview.md" >}}) provide to provision AWS resources needed by 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/usage/with-terraform.md index 32869dc9d..492d4e6ab 100644 --- a/content/geodesic/module/usage/with-terraform.md +++ b/content/geodesic/module/usage/with-terraform.md @@ -1,55 +1,55 @@ --- -title: "Using Geodesic with Terraform" -description: "Learn how to use Geodesic to manage Terraform resources" +title: "Using Geodesic Module with Terraform" +description: "Learn how to use Geodesic Module to manage Terraform resources" weight: -1 --- -# Bootstrap Process - -Run this process the very first time you setup the tfstate bucket. - -**IMPORTANT:** This has already been performed for this account, so this is documented here just for reference. - -Ensure the following environment variables have been set in the `Dockerfile`: -``` -ENV TF_BUCKET="joany-staging-terraform-state" -ENV TF_BUCKET_REGION="us-west-2" -ENV TF_DYNAMODB_TABLE="joany-staging-terraform-state-lock" -``` - -Then run these commands: - -1. Comment out the `s3 { ... }` section in `main.tf` - -2. Run `init-terraform` - -3. Run `terraform apply` - -4. Re-enable `s3 { ... }` section in `main.tf` - -5. Re-run `init-terraform`, answer `yes` when asked to import state - {{% dialog type="warning" icon="fa fa-exclamation-circle" title="Prerequisites" %}} Follow the "Use geodesic module" to [Use](/geodesic/module/usage/) get how to use the module shell. {{% /dialog %}} -# Create terraform state bucket - {{% dialog type="important" icon="fa fa-exclamation-triangle" title="Important" %}} To use terraform you need to create terraform state bucket. Follow the instructions to do that. {{% /dialog %}} +# Create terraform state bucket + To create terraform state bucket follow this steps: +## Config environment variables +Add to module `Dockerfile` environment variables + +``` +ENV TF_VAR_tfstate_namespace={PROJECT_NAME} +ENV TF_VAR_tfstate_stage={ENVIRONMENT_NAME} +ENV TF_VAR_tfstate_region={AWS_REGION} +ENV TF_BUCKET_REGION={AWS_REGION} +``` + +Replace placeholders `{%}` with values specific for your project. + +{{< dialog type="code-block" icon="fa fa-code" title="Example" >}} +``` +ENV TF_VAR_tfstate_namespace=example +ENV TF_VAR_tfstate_stage=staging +ENV TF_VAR_tfstate_region=us-west-2 +ENV TF_BUCKET_REGION=us-west-2 +``` +{{< /dialog >}} + +## Rebuild module +[Rebuild](/geodesic/module/usage/) the module +```shell +> make build +``` ## Add tfstate-bucket backing service Create file in `./conf/tfstate-backend/main.tf` with following content -##### ./conf/tfstate-backend/main.tf -```haml +{{% dialog type="code-block" icon="fa fa-code" title="./conf/tfstate-backend/main.tf" %}} +``` terraform { required_version = ">= 0.11.2" - backend "s3" {} } @@ -97,43 +97,18 @@ output "tfstate_backend_dynamodb_table_id" { output "tfstate_backend_dynamodb_table_arn" { value = "${module.tfstate_backend.dynamodb_table_arn}" } - -``` - -## Config tfstate-bucket backing service -Add to module `Dockerfile` environment variables - -##### Dockerfile -```text -ENV TF_VAR_tfstate_namespace={PROJECT_NAME} -ENV TF_VAR_tfstate_stage={ENVIRONMENT_NAME} -ENV TF_VAR_tfstate_region={AWS_REGION} -``` - -Replace placeholders `{%}` with values specific for your project. - -##### Example -```text -ENV TF_VAR_tfstate_namespace=example -ENV TF_VAR_tfstate_stage=staging -ENV TF_VAR_tfstate_region=us-west-2 -``` - -## Rebuild module -[Rebuild](/geodesic/module/usage/) the module -```bash -> make build ``` +{{% /dialog %}} ## Run into the module shell -Run the Geodesic shell. -```bash +Run the Geodesic Module shell. +```shell > $CLUSTER_NAME ``` {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} -```shell +``` > staging.example.com # Mounting /home/goruha into container # Starting new staging.example.com session from cloudposse/staging.example.com:dev @@ -168,7 +143,7 @@ assume-role ``` {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} -```shell +``` ❌ (none) tfstate-backend ➤ assume-role Enter passphrase to unlock /conf/.awsvault/keys/: Enter token for arn:aws:iam::xxxxxxx:mfa/goruha: 781874 @@ -180,18 +155,33 @@ Enter token for arn:aws:iam::xxxxxxx:mfa/goruha: 781874 ``` {{% /dialog %}} +## Save terraform state to local + +Comment in `./conf/tfstate-backend/main.tf` with `vim` + +```text +# backend "s3" {} +``` + +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} +``` +⧉ staging example +✅ (example-staging-admin) ~ ➤ vim /conf/tfstate-backend/main.tf +``` +{{% /dialog %}} + ## Apply tfstate-bucket Change directory to `/conf/tfstate-backet` and run there commands -```bash +```shell init-terraform terraform plan terraform apply ``` -The latest command will output id of terraform state bucket and dynamo DB table. Please copy that values because we need it for next step. +The latest command will output id of terraform state bucket and dynamo DB table. Please copy that values because we need it for next steps. {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} -```shell +``` ✅ (example-staging-admin) tfstate-backend ➤ terraform apply null_resource.default: Refreshing state... (ID: 4514126170089387416) null_resource.default: Refreshing state... (ID: 5129624787293790468) @@ -216,11 +206,39 @@ tfstate_backend_s3_bucket_id = example-staging-terraform-state In the example the bucket name is `example-staging-terraform-state` and dynamo DB table `example-staging-terraform-state-lock`. +## Save terraform state to s3 + +Uncomment in `./conf/tfstate-backend/main.tf` with `vim` + +```text + backend "s3" {} +``` + +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} +``` +⧉ staging example +✅ (example-staging-admin) ~ ➤ vim /conf/tfstate-backend/main.tf +``` +{{% /dialog %}} + +Change directory to `/conf/tfstate-backet` and run there commands +```shell +export TF_BUCKET={TERRAFORM_STATE_BUCKET_NAME} +terraform apply +``` + +{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} +``` +export TF_BUCKET=example-staging-terraform-state +terraform apply +``` +{{% /dialog %}} + ## Exit the module shell Exit from the shell by running `exit` twice {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} -```shell +``` ✅ (example-staging-admin) tfstate-backend ➤ exit logout Goodbye @@ -232,79 +250,36 @@ Goodbye ``` {{% /dialog %}} -## Set the bucket as default bucket to store for terraform state files -Update in module `Dockerfile` environment variables -```Dockerfile -# Terraform -ENV TF_BUCKET "" -ENV TF_BUCKET_REGION "us-east-1" -ENV TF_DYNAMODB_TABLE "" -``` -with terraform state bucket name and region and dynamo DB table name. +## Config environment variables +Add to module `Dockerfile` environment variable -### Example -```text -# Terraform -ENV TF_BUCKET "example-staging-terraform-state" -ENV TF_BUCKET_REGION "us-west-2" -ENV TF_DYNAMODB_TABLE "example-staging-terraform-state-lock" ``` - -## Rebuild the module -[Rebuild](/geodesic/module/usage/) the module -```bash -> make build +ENV TF_BUCKET={TERRAFORM_STATE_BUCKET_NAME} ``` -## Run into the module shell and authorize on AWS - -Run the Geodesic shell: +Replace placeholders `{%}` with values specific for your project. -```bash -> $CLUSTER_NAME -> assume-role +{{< dialog type="code-block" icon="fa fa-code" title="Example" >}} ``` +ENV TF_BUCKET=example-staging-terraform-state +``` +{{< /dialog >}} -{{% dialog type="code-block" icon="fa fa-code" title="Example" %}} +## Rebuild module +[Rebuild](/geodesic/module/usage/) the module ```shell -> staging.example.com -# Mounting /home/goruha into container -# Starting new staging.example.com session from cloudposse/staging.example.com:dev -# Exposing port 41179 -* Started EC2 metadata service at http://169.254.169.254/latest - - _ _ _ - ___| |_ __ _ __ _(_)_ __ __ _ _____ ____ _ _ __ ___ _ __ | | ___ - / __| __/ _` |/ _` | | '_ \ / _` | / _ \ \/ / _` | '_ ` _ \| '_ \| |/ _ \ - \__ \ || (_| | (_| | | | | | (_| | | __/> < (_| | | | | | | |_) | | __/ - |___/\__\__,_|\__, |_|_| |_|\__, | \___/_/\_\__,_|_| |_| |_| .__/|_|\___| - |___/ |___/ |_| - - -IMPORTANT: -* Your $HOME directory has been mounted to `/localhost` -* Use `aws-vault` to manage your sessions -* Run `assume-role` to start a session - - --> Run 'assume-role' to login to AWS - ⧉ staging example -❌ (none) tfstate-backend ➤ assume-role -Enter passphrase to unlock /conf/.awsvault/keys/: -Enter token for arn:aws:iam::xxxxxxx:mfa/goruha: 781874 -* Assumed role arn:aws:iam::xxxxxxx:role/OrganizationAccountAccessRole --> Run 'init-terraform' to use this project - ⧉ staging example -✅ (example-staging-admin) tfstate-backend ➤ +> make build ``` -{{% /dialog %}} -## Save `tfstate-bucket` terraform state file into the bucket -This is kind of self-reference but we need to store state in reliable storage. This is useful for the future update. +Now `tfstate-bucket` created you and the module configured to use it for the other terraform modules and kops +# Use with other terraform modules -# Create Terraform Module +With terraform modules you can provision any types of resources. +That modules will store terraform state on s3 `tfstate-bucket` prefixed with `name` of module. +Follow to create a terraform module and provision resources with it. +## Create terraform module To provision terraform module create a directory for it in `/conf` {{% dialog type="tip" icon="fa fa-hand-o-right" title="Tip" %}} @@ -312,7 +287,7 @@ If the terraform module is named `kube2iam`, then create `/conf/kube2iam` and st Example of code you can find there [LINK!] {{% /dialog %}} -# Rebuild the Geodesic Module +## Rebuild the Geodesic Module Rebuild the shell container with `make build` command. @@ -320,7 +295,7 @@ Rebuild the shell container with `make build` command. During development, you can skip rebuilding the container and instead work from the `/localhost` folder inside of the container. The `/localhost` folder is the user's `$HOME` folder mounted into the container. Any files on this system will be persisted. {{% /dialog %}} -# Run the shell +## Run the shell ```bash $CLUSTER_NAME ``` @@ -328,12 +303,12 @@ $CLUSTER_NAME For example, to access your geodesic project shell do the following. If `$CLUSTER_NAME=staging.example.com` simply run the command `staging.example.com`. -# Login to AWS with your MFA device +## Login to AWS with your MFA device ```bash assume-role ``` -# Provision terraform module +## Provision terraform module Change directory to the required resources folder ```bash @@ -348,7 +323,7 @@ terraform apply {{% dialog type="code-block" icon="fa fa-code" title="Example" %}} If terraform module name is `kube2iam`. -```bash +``` cd /conf/kube2iam init-terraform terraform plan @@ -356,7 +331,9 @@ terraform apply ``` {{% /dialog %}} -## Example: Provision CloudTrail with Terraform +## Examples + +### Provision CloudTrail with Terraform Change directory to the required resources folder ```bash @@ -371,8 +348,8 @@ terraform apply ``` ![Terraform Plan Output of Cloud Trail](/assets/81d14ff-cloudtrail.png) -## Example: Provision Backing Services with Terraform +### Provision Backing Services with Terraform Change directory to the required resources folder ```bash cd /conf/backing-services diff --git a/layouts/shortcodes/dialog.html b/layouts/shortcodes/dialog.html index 479d77d61..55c0ec763 100755 --- a/layouts/shortcodes/dialog.html +++ b/layouts/shortcodes/dialog.html @@ -1,4 +1,4 @@

{{ .Get "title" }}

-

{{ .Inner }}

+

{{ .Inner | markdownify }}

diff --git a/static/css/custom.css b/static/css/custom.css index b8c6e250f..34a1d528a 100644 --- a/static/css/custom.css +++ b/static/css/custom.css @@ -1056,7 +1056,7 @@ footer .footline .date { padding-top: 0; position:relative; left: -4rem; - width: 116%; + width: 113%; } .dialog.code-block pre { @@ -1065,6 +1065,7 @@ footer .footline .date { padding-top: 5px; padding-right: 13px; padding-bottom: 5px; + border-radius: 0; } .dialog.code-block h4 {