Document how to get started #108

osterman · 2018-06-01T00:30:17Z

what

Given an overview of "getting started" with the Cloud Posse solution
Explain the relationship between all the components
Emphasize the tools that they must know/understand
Content redirects (per Add Support for Redirect Front Matter #17)

why

Our GitHub and Documentation portal has an overwhelming amount of information
We need a way to document "just the right amount" of information to get users familiar with the solution
This will be forever a WIP

…ting-started

aknysh · 2018-06-04T15:52:13Z

content/documentation/getting-started.md

+Helm is central to how we deploy all services on kubernetes.
+
+* [helm]({{< relref "tools/helm.md" >}}) is essentially the package manager for Kubernetes (like `npm` for Node, `gem` for Ruby, and `rpm` for RHEL)
+* [helm charts](/helm-charts/) are how kubernetes resources are templatized using go templates


Go (capitalize language names)?

aknysh · 2018-06-04T17:20:10Z

content/geodesic/module/_index.md

@@ -5,3 +5,49 @@ description: "Geodesic modules are Git repositories that extend the Geodesic bas
 {{% dialog type="info" icon="fa fa-book" title="Read More" %}}
 ⇠ Select one of these pages to learn more about the topic.
 {{% /dialog %}}
+
+We believe that infrastructure as code should be treated just like all other code: tested, bundled into artifacts and automatically deployed. This is what `geodesic` solves. A geodesic module is a docker container/image contains all the code necessary deploy infrastructure.


A geodesic module is a docker container/image containing

Grammatically, I think the sentence should be "A geodesic module is a docker container/image which contains all the code necessary to deploy infrastructure" except I still don't know what that means. Maybe it's supposed to be "...all the code necessary to deploy itself"?

@Nuru thanks for checking this out.

How is this? I really want to make sure this is clear. If you don't understand it, others won't either.

A geodesic module is a docker container/image which contains all the Infrastructure as Code necessary to provsion logically related IaaS resources (e.g. AWS Organizations, IAM Roles/Permissions, CDNs, S3 Buckets, Kubernetes Clusters, etc).

aknysh · 2018-06-04T17:23:54Z

content/geodesic/module/_index.md

+- [Multi-stage Docker Builds]({{< relref "tools/docker/best-practices.md#multi-stage-builds" >}})
+- [Terraform Root modules]({{< relref "terraform-modules/root/_index.md" >}})
+- [Terraform Modules](/terraform-modules/)
+- [Polyrepos]({{< relref "glossary/polyrepo.md" >}}) to logically organize infrastructure. Use modules to import logic.


to logically organize infrastructure and use modules to import logic

aknysh · 2018-06-04T17:25:04Z

content/geodesic/module/_index.md

+- [Terraform Modules](/terraform-modules/)
+- [Polyrepos]({{< relref "glossary/polyrepo.md" >}}) to logically organize infrastructure. Use modules to import logic.
+
+We prefer the polyrepo approach to the monorepo approach when it comes in infrastructure. Git repositories allow us to surgically tag/version parts of infrastructure.


to infrastructure

Reworded.

Git repositories allow us to surgically tag/version infrastructure code that represents some kind of business logic.

aknysh · 2018-06-04T18:04:44Z

content/geodesic/module/_index.md

+
+The [`root.cloudposse.co`](https://github.com/cloudposse/root.cloudposse.co) module represents an organization's "root" or "top level" AWS account. This is typically your billing organization and handles IAM user account provisioning.
+
+It should also use the `terraform` resource  [`aws_organizations_organization`](https://www.terraform.io/docs/providers/aws/r/organizations_organization.html) to provision all the subaccounts below.


and organizations_account

aknysh · 2018-06-04T18:06:09Z

content/geodesic/module/_index.md

+
+## prod.cloudposse.co
+
+The [`prod.cloudposse.co`](https://github.com/cloudposse/prod.cloudposse.co) module represents an organization's "production infrastructure". It's a subaccount (organization) of the [`root.cloudposse.co`](https://github.com/cloudposse/root.cloudposse.co).


It's a subaccount (organization)

Organization here sounds overloaded.
Maybe just subaccount or member account?

aknysh · 2018-06-04T18:07:12Z

content/geodesic/module/_index.md

+
+## dev.cloudposse.co
+
+The [`dev.cloudposse.co`](https://github.com/cloudposse/dev.cloudposse.co) module represents an organization's "development infrastructure". This module is used as a sandbox environment where developers and test the waters and get familiar with AWS. We prescribe that organizations give all developers "Administrator" level privileges to this account in order to give them an unfettered opporutnity at developing infrastructure.


where developers test the waters

Nice simplification. Always point these out to me.

aknysh · 2018-06-04T18:09:03Z

content/geodesic/module/_index.md

+
+## audit.cloudposse.co
+
+The [`audit.cloudposse.co`](https://github.com/cloudposse/audit.cloudposse.co) module represents an organization's "audit logs infrastructure".  By leveraging our [`terraform-aws-cloudtrail`](https://github.com/cloudposse/terraform-aws-cloudtrail) and [`terraform-aws-cloudtrail-s3-bucket`](https://github.com/cloudposse/terraform-aws-cloudtrail-s3-bucket)  modules, we make it exceptionally easy to ship CloudTrail logs from all your organizations to one central, highly restrictive organization whose sole purpose is to provide a tamper-proof, encrypted, system of record for infrastructure logs with [lifecycle rules]({{< relref "terraform/tips-tricks.md#s3-bucket-lifecycle-rules" >}}).


from all your organizations

From all your accounts in the organization?
Or from Organizational Units (OUs)?

highly restrictive organization

highly restrictive account?

aknysh · 2018-06-04T18:10:51Z

content/geodesic/module/_index.md

+
+## testing.cloudposse.co
+
+The [`testing.cloudposse.co`](https://github.com/cloudposse/testing.cloudposse.co) module represents an organization used for continuous integration testing of infrastructure code. By provisioning a separate, dedicated organization for this we are able to silo testing infrastructure so it doesn't pollute or in any way impact other environments.


represents an organizational unit used for continuous integration?

for continuous integration and testing of infrastructure code

By provisioning a separate, dedicated organizational unit (or just account) for this

aknysh · 2018-06-04T18:15:42Z

content/glossary/monorepo.md

+tags:
+- polyrepo
+- monorepo
+description: "Monorepo refers to a strategy of storing all code for possibly unrelated applications with in the same source code repository."


aknysh · 2018-06-04T18:16:37Z

content/glossary/stage.md

@@ -3,10 +3,18 @@ title: "Stage"
 description: 'One of the phases in the SDLC where by software is deployed to an environment. Common stages are “Production”, “Staging”, “QA” or “Development”'


aknysh · 2018-06-04T18:17:16Z

content/glossary/stage.md

 tags:
 - environment
 - sdlc
 - prod
 - staging
 - dev
 ---
+
+It's important to note that within a given stage, there might be multiple environments. We always prescribe separating multiple stages by using multiple AWS organizations. Then provisioning multiple environments within that stage as necessary.


by using multiple AWS accounts or organizational units

aknysh · 2018-06-04T18:17:46Z

content/glossary/stage.md

+
+It's important to note that within a given stage, there might be multiple environments. We always prescribe separating multiple stages by using multiple AWS organizations. Then provisioning multiple environments within that stage as necessary.
+
+For example, the "staging" organization might run "pre-production" and "QA" environments.


the "staging" account?

aknysh · 2018-06-04T18:24:27Z

content/terraform-modules/root/examples/Dockerfile

@@ -0,0 +1,10 @@
+FROM r.cfcr.io/cloudposse/terraform-root-modules:0.1.0 as terraform-root-modules


should we get it from Docker Hub instead of CodeFresh for the example?

aknysh · 2018-06-04T18:24:50Z

content/terraform-modules/root/_index.md


+Here's what it looks like in practice: (only relevant portions)
+
+{{% include-code-block title="" file="terraform-modules/root/examples/Dockerfile" language="Dockerfile Snippet" %}}


is it correct language="Dockerfile Snippet"?

aknysh · 2018-06-04T18:26:09Z

content/terraform/tips-tricks.md

+{{% include-code-block title="Example: Encrypted S3 Bucket" file="terraform/examples/encrypted-s3-bucket.tf" language="hcl" %}}
+
+For an example of how we use it, check out our [`terraform-aws-s3-log-storage`](https://github.com/cloudposse/terraform-aws-s3-log-storage) module.
+
 # Use Pre Commit Hooks for Linting

 We strongly urge that all code be linted prior to checking into to git. Running `terraform fmt` on the codebase before committing will accomplish this.


aknysh · 2018-06-04T18:28:01Z

content/tools/docker/best-practices.md

+
+Inheritance is when you use `FROM some-image:1.2.3` (vs `FROM scratch`) in a `Dockerfile`. We recommend to leverage lean base images (E.g. `alpine` or `busybox`).
+
+Try to leverage the same base image as many of your images as possible for faster `docker pulls`.


in as many of your images

aknysh · 2018-06-04T18:31:26Z

content/tools/docker/best-practices.md

+
+# Use Scratch Base Image
+
+One often overlooked, ultimately lean base-image is the `scratch` image. This is an empty filesystem which allows one to copy/distribute the minimal set of artifacts. For languages that can compile statically linked binaries, using the `scratch` base image is the most secure docker image as there will be no other exploitable packages in the image.


using the scratch base image is the most secure way

aknysh · 2018-06-04T18:33:05Z

content/tools/helm.md

 ---

+{{< img src="/assets/helm-d7685fec.png" title="Helm Logo" class="logo" >}}
+
 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.


an application

aknysh · 2018-06-04T18:33:34Z

content/tools/helm.md

 ---

+{{< img src="/assets/helm-d7685fec.png" title="Helm Logo" class="logo" >}}
+
 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.


deploy a full-fledged application

aknysh

Nicely written, just a few comments

…docs into feature-document-chartmuseum * 'feature-document-chartmuseum' of github.com:cloudposse/docs: Document how to get started (#108) re-enable github link validation (#107)

Document how to get started

180c614

osterman added wip documentation customer labels Jun 1, 2018

osterman and others added 13 commits May 31, 2018 18:04

expand on geodesic modules

77cb01a

Merge branch 'master' into getting-started

cbcd68c

Expand getting started

3b7fcd1

Merge branch 'getting-started' of github.com:cloudposse/docs into get…

0fa704e

…ting-started

Fix links

a403737

Add missing page

bee08ca

css tweaks

8a46b5d

fix ci

ef75e49

add getting started button

e4f6fa1

add logos

af7a477

Add automatic redirects

4606996

wip

2a1527c

fix links

2b04bf7

osterman requested review from goruha, aknysh and sarkis June 4, 2018 03:02

osterman added 3 commits June 3, 2018 20:09

define iac. fix typos

1585cb0

add coming soon

68d04f4

reformat

3ff12e8

osterman removed the wip label Jun 4, 2018

osterman mentioned this pull request Jun 4, 2018

Cheat Sheet #20

Open

aknysh reviewed Jun 4, 2018

View reviewed changes

address CR comments

1cc63ee

osterman self-assigned this Jun 5, 2018

address CR comments

68c3b58

aknysh approved these changes Jun 5, 2018

View reviewed changes

osterman merged commit 17523e7 into master Jun 5, 2018

osterman deleted the getting-started branch June 5, 2018 02:45

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document how to get started #108

Document how to get started #108

osterman commented Jun 1, 2018 •

edited

Loading

aknysh Jun 4, 2018

aknysh Jun 4, 2018

Nuru Jun 4, 2018

osterman Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

osterman Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

osterman Jun 5, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

osterman Jun 5, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh Jun 4, 2018

aknysh left a comment


		The [`root.cloudposse.co`](https://github.com/cloudposse/root.cloudposse.co) module represents an organization's "root" or "top level" AWS account. This is typically your billing organization and handles IAM user account provisioning.

		It should also use the `terraform` resource [`aws_organizations_organization`](https://www.terraform.io/docs/providers/aws/r/organizations_organization.html) to provision all the subaccounts below.


		## prod.cloudposse.co

		The [`prod.cloudposse.co`](https://github.com/cloudposse/prod.cloudposse.co) module represents an organization's "production infrastructure". It's a subaccount (organization) of the [`root.cloudposse.co`](https://github.com/cloudposse/root.cloudposse.co).


		## dev.cloudposse.co

		The [`dev.cloudposse.co`](https://github.com/cloudposse/dev.cloudposse.co) module represents an organization's "development infrastructure". This module is used as a sandbox environment where developers and test the waters and get familiar with AWS. We prescribe that organizations give all developers "Administrator" level privileges to this account in order to give them an unfettered opporutnity at developing infrastructure.


		## audit.cloudposse.co

		The [`audit.cloudposse.co`](https://github.com/cloudposse/audit.cloudposse.co) module represents an organization's "audit logs infrastructure". By leveraging our [`terraform-aws-cloudtrail`](https://github.com/cloudposse/terraform-aws-cloudtrail) and [`terraform-aws-cloudtrail-s3-bucket`](https://github.com/cloudposse/terraform-aws-cloudtrail-s3-bucket) modules, we make it exceptionally easy to ship CloudTrail logs from all your organizations to one central, highly restrictive organization whose sole purpose is to provide a tamper-proof, encrypted, system of record for infrastructure logs with [lifecycle rules]({{< relref "terraform/tips-tricks.md#s3-bucket-lifecycle-rules" >}}).


		## testing.cloudposse.co

		The [`testing.cloudposse.co`](https://github.com/cloudposse/testing.cloudposse.co) module represents an organization used for continuous integration testing of infrastructure code. By provisioning a separate, dedicated organization for this we are able to silo testing infrastructure so it doesn't pollute or in any way impact other environments.

		@@ -3,10 +3,18 @@ title: "Stage"
		description: 'One of the phases in the SDLC where by software is deployed to an environment. Common stages are “Production”, “Staging”, “QA” or “Development”'


		It's important to note that within a given stage, there might be multiple environments. We always prescribe separating multiple stages by using multiple AWS organizations. Then provisioning multiple environments within that stage as necessary.

		For example, the "staging" organization might run "pre-production" and "QA" environments.

		@@ -0,0 +1,10 @@
		FROM r.cfcr.io/cloudposse/terraform-root-modules:0.1.0 as terraform-root-modules


		Here's what it looks like in practice: (only relevant portions)

		{{% include-code-block title="" file="terraform-modules/root/examples/Dockerfile" language="Dockerfile Snippet" %}}


		Inheritance is when you use `FROM some-image:1.2.3` (vs `FROM scratch`) in a `Dockerfile`. We recommend to leverage lean base images (E.g. `alpine` or `busybox`).

		Try to leverage the same base image as many of your images as possible for faster `docker pulls`.


		# Use Scratch Base Image

		One often overlooked, ultimately lean base-image is the `scratch` image. This is an empty filesystem which allows one to copy/distribute the minimal set of artifacts. For languages that can compile statically linked binaries, using the `scratch` base image is the most secure docker image as there will be no other exploitable packages in the image.

Document how to get started #108

Document how to get started #108

Conversation

osterman commented Jun 1, 2018 • edited Loading

what

why

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aknysh left a comment

Choose a reason for hiding this comment

osterman commented Jun 1, 2018 •

edited

Loading