a bit more documentation cleanup

wework · Dec 4, 2018 · a03b8c6 · a03b8c6
1 parent 22bc0f5
commit a03b8c6
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 31 deletions.
diff --git a/README.md b/README.md
@@ -18,18 +18,22 @@ The latest Debian Stretch release can be pulled from `quay.io/reactiveops/ci-ima
 
 ## 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)
-- CI Specific Documentation
-  - CircleCI
-  - GitLab CI
-  - Bitbucket Pipelines
-- [Releasing New Versions of rok8s-scripts](docs/releasing.md)
+- [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)
+
+### CI Specific Documentation
+- CircleCI
+- GitLab CI
+- Bitbucket Pipelines
+
+### Contributing
+- [Releasing New Versions of rok8s-scripts](/docs/releasing.md)
 
 ## License
 Apache License 2.0

diff --git a/docs/helm.md b/docs/helm.md
@@ -30,7 +30,7 @@ app-dir/
 
 In the above structure we've added a Helm chart, which we won't be outlining here. The other additional files and folder we'll outline below.
 
-## rok8s-scripts Config
+## Configuration
 The `deploy/development.config` file here is a rok8s-scripts config file for the development environment.
 
 ```bash
@@ -53,9 +53,9 @@ image: 012345678911.dkr.ecr.us-east-1.amazonaws.com/app
 somevalue: anothervalue
 ```
 
-## Sops Secrets
+## Secret Management
 
-Helm stores release information in Config Maps. If we deployed Kubernetes Secrets with Helm, they'd also be visible in that Helm release Config Map. To avoid that, we manage secrets separately with Helm. Please see [Secret Encryption with Sops](docs/sops.md) for further information.
+Helm stores release information in Config Maps. If we deployed Kubernetes Secrets with Helm, they'd also be visible in that Helm release Config Map. To avoid that, we manage secrets separately. Please see [Managing Kubernetes Secrets Securely](/docs/secrets.md) for further information.
 
 ## Deploying it All
 
@@ -69,7 +69,7 @@ helm-deploy -f deploy/development.config
 
 This script reads the rok8s-scripts config file (`deploy/development.config`) and runs a Helm upgrade or install with the given values files.
 
-Importantly, it will set the `image.tag` value to `CI_SHA1`, a value that should match the tag of your latest pushed image. There's more info available in our [Docker documentation](docs/docker.md) on how these images are tagged and pushed.
+Importantly, it will set the `image.tag` value to `CI_SHA1`, a value that should match the tag of your latest pushed image. There's more info available in our [Docker documentation](/docs/docker.md) on how these images are tagged and pushed.
 
 ## Advanced Configuration
 

diff --git a/docs/index.md b/docs/index.md
@@ -1,6 +1,6 @@
 # rok8s-scripts
 
-This is a set of scripts that are useful for CI/CD workflows with Docker and Kubernetes. These simplify secrets management, environment specific config, Docker build caching, and much more.
+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.
 
 ## CI Images
 
@@ -17,19 +17,22 @@ We currently include a variety of CI Images, including Alpine and Debian Stretch
 The latest Debian Stretch release can be pulled from `quay.io/reactiveops/ci-images:v7-stretch`. A full list of the latest image tags is available on our [Quay repository](https://quay.io/repository/reactiveops/ci-images).
 
 ## 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)
 
-- [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)
-- CI Specific Documentation
-  - CircleCI
-  - GitLab CI
-  - Bitbucket Pipelines
-- [Releasing New Versions of rok8s-scripts](docs/releasing.md)
+### Cloud Specific Documentation
+- [Amazon Web Services](/docs/aws.md)
+- [Google Cloud](/docs/gcp.md)
+
+### CI Specific Documentation
+- CircleCI
+- GitLab CI
+- Bitbucket Pipelines
+
+### Contributing
+- [Releasing New Versions of rok8s-scripts](/docs/releasing.md)
 
 ## License
 Apache License 2.0

diff --git a/docs/without_helm.md b/docs/without_helm.md
@@ -1,5 +1,5 @@
 # Deploying to Kubernetes without Helm
-Although [Helm](docs/helm.md) is our preferred method of deploying to Kubernetes,  rok8s-scripts also supports deploying to Kubernetes without Helm.
+Although [Helm](/docs/helm.md) is our preferred method of deploying to Kubernetes, rok8s-scripts also supports deploying to Kubernetes without Helm.
 
 ## Initial Project Structure
 All rok8s-scripts configuration lives in a `deploy` directory at the root of your project by default. In this example, we have a simple Python app with a Dockerfile in place.
@@ -26,10 +26,31 @@ app-dir/
 └── requirements.txt
 ```
 
+Each Kubernetes resource config lives in the `deploy` directory of this repo, with filenames matching the desired rok8s-scripts format (see below for a full list). In this example, each environment has unique configuration in the form of a secret, config map, and HPA. Beyond those resources, each environment would share the deployment and migration configuration.
+
+In the example above, the `development.config` rok8s-scripts configuration file would look something like:
+
+```bash
+CONFIGMAPS=("development/app-env")
+SOPS_SECRETS=("development/app-env")
+BLOCKING_JOBS=("app-migrate")
+DEPLOYMENTS=("app")
+HORIZONTAL_POD_AUTOSCALERS=("development/app")
+```
+
+This full configuration could be deployed with the following rok8s-scripts command:
+
+```bash
+k8s-deploy-and-verify -f deploy/development.config
+```
+
+More indepth examples are available in the [examples directory](/examples).
+
+
 ## Deployment Configuration
 Listed below are all the types of resources rok8s-scripts supports. In all cases, the filename suffix is important and must match the spec precisely.
 
-```
+```bash
 # Cluster Namespace to work in
 NAMESPACE='default'