update documentation (FairwindsOps#265)

* update documentation

* split up example readmes

* Minor tweaks

* recommend a safer flow for k8s auth

* add docs for cloud provider auth

CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

Makefile

@@ -0,0 +1,6 @@
+docs-index:
+	cat README.md \
+	| sed 's/\[\(.*\)\](\(\w\+\.md\))/[\1](https:\/\/github.com\/reactiveops\/rok8s-scripts\/tree\/master\/\2)/g' \
+	| sed 's/\[\(.*\)\](\/\?docs\/\(.*\))/[\1](\2)/g' \
+	| sed 's/\[\(.*\)\](\(\/.*\))/[\1](https:\/\/github.com\/reactiveops\/rok8s-scripts\/tree\/master\2)/g' \
+	> docs/index.md

README.md

@@ -1,31 +1,64 @@
-[![CircleCI](https://circleci.com/gh/reactiveops/rok8s-scripts.svg?style=svg)](https://circleci.com/gh/reactiveops/rok8s-scripts)
+[![Version][version-image]][version-link] [![CircleCI][circleci-image]][circleci-link]
+
+[version-image]: https://img.shields.io/static/v1.svg?label=Version&message=8.0.2&color=239922
+[version-link]: https://github.com/reactiveops/rok8s-scripts
+[circleci-image]: https://circleci.com/gh/reactiveops/rok8s-scripts.svg?style=svg
+[circleci-link]: https://circleci.com/gh/reactiveops/rok8s-scripts
 
 # rok8s-scripts
 
-This is a set of opinionated scripts for managing application development and deployment lifecycle using Kubernetes. These simplify secure secrets management, environment specific config, Docker build caching, and much more.
+rok8s-scripts is a framework for building GitOps workflows with Docker and Kubernetes.
+By adding rok8s-scripts to your CI/CD pipeline, you can build, push, and deploy your applications using the
+set of best practices we've built at ReactiveOps.
+
+In addition to building Docker images and deploying them to Kubernetes, rok8s-scripts is a great way to handle
+secure secrets management, environment specific configuration, Docker build caching, and much more.
 
 **Want to learn more?** ReactiveOps holds [office hours on Zoom](https://zoom.us/j/242508205) the first Friday of every month, at 12pm Eastern. You can also reach out via email at `[email protected]`
 
-## CI Images
+### Quickstart
+To help you get started quickly, we've built a [minimal example](/examples/minimal)
+that shows how to use rok8s-scripts to build Docker images and deploy to Kubernetes
+using Circle CI. This example will serve as a helpful introduction regardless of your CI platform.
 
-Each new release of rok8s-scripts comes with a new set of CI images for simple workflows. These CI images include a set of common CI/CD dependencies, including Docker, Kubernetes, Helm, AWS, and Google Cloud client libraries. Starting with these images as a base for deployment workflows should ensure that you don't need to spend any build time installing extra dependencies.
+## Documentation
+We've created documentation for several different use cases and workflows where rok8s-scripts can help.
 
-We currently include a variety of CI Images, including Alpine and Debian Stretch as our recommended starting points. In certain cases you may want to use our images that include Node.js or Golang.
+* [Build and push Docker images](docs/docker.md) - This is the place to start to get a sense
+for rok8s-scripts project structure and a very basic use case
+* [Deploy to Kubernetes](docs/without_helm.md) - Learn how to get your applications into staging
+and production.
+* [Deploy to Kubernetes with Helm](docs/helm.md) - If you've built a Helm chart for your application,
+rok8s-scripts is a great way to deploy your chart to staging and production
+* [Manage secrets](docs/secrets.md) - Learn how rok8s-scripts can simplify and secure your secret management workflows
 
-The latest Debian Stretch release can be pulled from `quay.io/reactiveops/ci-images:v8-stretch`. A full list of the latest image tags is available on our [Quay repository](https://quay.io/repository/reactiveops/ci-images).
+### Cloud-specific Documentation
+* [Deploy to AWS](docs/aws.md) - Learn how to authenticate and deploy using rok8s-scripts with aws-cli
+* [Deploy to GCP](docs/gcp.md) - Learn how to authenticate and deploy using rok8s-scripts with gcloud
 
 ## Examples
 
-rok8s-scripts is designed to work well in a wide variety of environments. That includes Bitbucket Pipelines, CircleCI, GitLab CI, and more. There are many valid ways to configure CI pipelines, we've includes a variety of [examples](/examples) in this repository.
-
-Most notably, the CI example includes sample configuration for the following platforms:
+rok8s-scripts is designed to work well with a wide variety of use cases and environments.
+There are many valid ways to configure CI pipelines, but to help you get started, we've included a variety of [examples](/examples) in this repository.
 
+### CI Platforms
 - [Bitbucket Pipelines](/examples/ci/bitbucket-pipelines.yml)
 - [CircleCI](/examples/ci/.circleci/config.yml)
 - [GitLab CI](/examples/ci/.gitlab-ci.yml)
 - [Jenkins](/examples/ci/Jenkinsfile)
 
-On their own, these examples may not make a lot of sense. There's a lot more documentation below that should cover everything included in these examples and more.
+### Miscellaneous examples
+- [External secrets manager](/examples/external-secrets-manager)
+- [SOPS secrets](/examples/sops-secrets) - Shows how to use [sops](https://github.com/mozilla/sops) with rok8s-scripts
+- [Using Helm](/examples/helm) - We recommend using Helm to manage your deployments
+- [Optional components](/examples/optional-components) - Turn components (e.g. Horizontal Pod Audoscaler) on and off depending on whether you're deploying to staging or production
+- [Production ready](/examples/production-ready) - Includes a number of recommended production features
+
+## CI Images
+
+Each new release of rok8s-scripts generates CI images for common workflows. These images include a set of common CI/CD dependencies, including Docker, Kubernetes, Helm, AWS, and Google Cloud client libraries. Starting with these images as a base for deployment workflows ensures that you don't need to spend any build time installing extra dependencies.
+
+We currently include CI Images based on Alpine and Debian Stretch as our recommended starting points. The latest Debian Stretch release can be pulled from `quay.io/reactiveops/ci-images:v8-stretch`. A full list of image tags is available on our [Quay repository](https://quay.io/repository/reactiveops/ci-images).
 
 ## Versioning v8.0.0 and beyond
 
@@ -47,18 +80,9 @@ You are okay with your pipeline breaking occasionally and having to upgrade thin
 
 In this case, go ahead and pin to a major version such as `v8-alpine`
 
-## Further Reading
-
-- [Building and Pushing Docker Images](/docs/docker.md)
-- [Deploying to Kubernetes with Helm](/docs/helm.md)
-- [Deploying to Kubernetes without Helm](/docs/without_helm.md)
-- [Managing Kubernetes Secrets Securely](/docs/secrets.md)
-
-### Cloud Specific Documentation
-- [Amazon Web Services](/docs/aws.md)
-- [Google Cloud](/docs/gcp.md)
 
 ### Contributing
+- [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Releasing New Versions of rok8s-scripts](/docs/releasing.md)
 
 ## License

docs/gcp.md

@@ -2,10 +2,19 @@
 It's quite straightforward to push Docker images to Google Container Registry and deploy to GKE clusters with rok8s-scripts.
 
 ## Google Cloud Credentials
-To connect to Google Cloud from a CI workflow, a GCP service account is recommended. This can be created from the Google Cloud Console. Credentials for this service account can be downloaded in JSON form. To load those into a rok8s-scripts CI workflow, they'll need to be base64 encoded. This can be accomplished with a command like this:
+To connect to Google Cloud from a CI workflow, a [GCP service account](https://console.cloud.google.com/iam-admin/serviceaccounts)
+is recommended. To create a service account:
+* [Go to the service accounts page](https://console.cloud.google.com/iam-admin/serviceaccounts)
+* Choose a name for the account (e.g. `rok8s-scripts`) and hit "Create"
+* For "Service account permissions", choose `Kubernetes Engine Developer` and hit "continue"
+* Click "Create Key" and choose "JSON"
+
+
+To load the JSON credentials into a rok8s-scripts CI workflow, they'll need to be base64 encoded.
+This can be accomplished with a command like this:
 
 ```bash
-cat downloaded_google_credentials.json | base64
+cat downloaded_google_credentials.json | base64 -w 0
 ```
 
 With those credentials in base64 format, you'll need to add them as a protected environment variable in your CI tool of choice. This environment variable needs to be named `GCLOUD_KEY`, and contain a base64 encoded copy of GCP Service Account credentials. It's important that this value is not checked into your codebase, as the credentials could potentially provide a great deal of access into your systems.
@@ -41,4 +50,4 @@ With the above environment variables in place, it's time to run a script to pull
 
 ```bash
 prepare-gcloud
-```
+```

docs/helm.md

@@ -43,6 +43,9 @@ HELM_VALUES=('development/app')
 
 You'll see that some of these configurations reference _similar_, but not exact, matches to the files above. Note `deploy/development/app.values.yml` translates to `HELM_VALUES=('development/app')`. The `deploy/development/app-env.secret.sops.yml` file translates to `SOPS_SECRETS=('development/app-env')`. **Note that if the files are not named with the expected extensions then rok8s-scripts will not work**.
 
+## Credentials
+See [Kubernetes auth](kubernetes_auth.md) to learn how to grant your CI pipeline access to your Kubernetes cluster
+
 ## Helm Values Files
 Helm uses values files to fill in chart templates. In this example, our values file is reference in rok8s-scripts config as `HELM_VALUES=('development/app')`, which maps to reading the `deploy/development/app.values.yml` file. A simple values file might look something like this: