cloudposse / docs

📘 SweetOps documentation for the Cloud Posse way of doing Infrastructure as Code. https://docs.cloudposse.com

Developer Documentation

Welcome to the Cloud Posse Developer Hub Documentation Portal.

All documentation is published to docs.cloudposse.com. Here you'll find comprehensive guides and documentation to help you start working with the Cloud Posse technology stack as quickly as possible, as well as support if you get stuck.

Let's jump right in! Here's how to get started with our documentation.

Usage

1. Build dependencies

make all

2. Start local web server

make start

Makefile Targets

Available targets:

  help                                Help screen
  help/all                            Display help for all targets
  help/short                          This help short screen

Related Projects

Check out these related projects.

• Geodesic - Geodesic is the fastest way to get up and running with a rock solid, production grade cloud platform

✨ Contributing

This project is under active development, and we encourage contributions from our community.

Many thanks to our outstanding contributors:

For 🐛 bug reports & feature requests, please use the issue tracker.

In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

1. Review our Code of Conduct and Contributor Guidelines.
2. Fork the repo on GitHub
3. Clone the project to your own machine
4. Commit changes to your own branch
5. Push your work back up to your fork
6. Submit a Pull Request so that we can review your changes

NOTE: Be sure to merge the latest changes from "upstream" before making a pull request!

🌎 Slack Community

Join our Open Source Community on Slack. It's FREE for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build totally sweet infrastructure.

📰 Newsletter

Sign up for our newsletter and join 3,000+ DevOps engineers, CTOs, and founders who get insider access to the latest DevOps trends, so you can always stay in the know. Dropped straight into your Inbox every week — and usually a 5-minute read.

📆 Office Hours

Join us every Wednesday via Zoom for your weekly dose of insider DevOps trends, AWS news and Terraform insights, all sourced from our SweetOps community, plus a live Q&A that you can’t find anywhere else. It's FREE for everyone!

License

This material may only be distributed subject to the terms and conditions set forth in the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License or later with the restrictions noted below (the latest version of the license is presently available at https://creativecommons.org/licenses/by-nc-sa/4.0/).

Attribution You must attribute the work in the manner specified by the author or licensor.

Noncommercial The licensor permits others to copy, distribute and transmit the work. In return, licensees may not use the work for commercial purposes — unless they get the licensor's permission.

Share Alike The licensor permits others to distribute derivative works only under the same license or one compatible with the one that governs the licensor's work.

Distribution

Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder.

Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is prohibited unless prior permission is obtained from the copyright holder.

Trademarks

All other trademarks referenced herein are the property of their respective owners.

---

Copyright © 2017-2024 Cloud Posse, LLC

docs's Issues

Add Support for Asciinema Screencasts

what

• add hugo shortcode for screencasts
• add platform-specific deps

why

• better documentation
• light weight streaming
• Most of our screencasts will be text based
• We can add all the .cast recordings to git

references

• https://fossies.org/linux/hugo/docs/layouts/shortcodes/asciicast.html
• http://gitbus.com/alimy/hugo/src/f4bf214137ebd24a0d12f16d3a98d9038e6eabd3/docs/layouts/shortcodes/asciicast.html

Investigate if Hugo will support `http_proxy` env

what

• Find out if hugo will respect http_proxy settings

why

• If so, then we can use a MITM proxy to inject github authorization token

Document Kube Lego Renewal Rate

what

• Notices are sent before there's any danger.

Implement Related Content

what

• List related pages at the bottom of certain articles

why

• Enhance discovery
• AddThis isn't very good (what we have now)
• It's natively supported by hugo

referneces

• https://gohugo.io/content-management/related/

Ensure Codefresh Caching is Working

what

• I suspect Codefresh is not persisting the cache for htmltest and hugo
• Hugo supports --cacheDir; see https://gohugo.io/templates/data-templates/#cache-urls

why

• Maybe because our working_dir is wrong

references

• https://codefresh.io/containers/caching-build-dependencies-codefresh-volumes/

Only Deploy on Tagged Releases

what

• Do not deploy to S3 for every merge to master

why

• This will trigger algolia reindexing
• Not all changes (e.g. Updating README.md) require redeployment

Document Common CI/CD Timeout Error

what

"chart-repo" has been added to your repositories                                                                                
exec: helm repo update --kube-context us-west-2-staging-example-co                                                                
Hang tight while we grab the latest from your chart repositories...                                                             
...Successfully got an update from the "cloudposse-incubator" chart repository                                                  
...Successfully got an update from the "stable" chart repository                                                                
...Successfully got an update from the "chart-repo" chart repository                                                            
Update Complete. ⎈ Happy Helming!⎈                                                                                              
exec: helm upgrade --install ch38827-app chart-repo/app --version 1.0.0-sha.1dd6919 --namespace ch38827 --values /code
fresh/volume/app/config/ch38827-app.yaml --wait --timeout=600 --recreate-pods --force --reset-values --kube
-context us-west-2-staging-example-co                                                                                             
Error: UPGRADE FAILED: timed out waiting for the condition                                                                      
err: exit status 1                                                                                                              
[SYSTEM] Error: Failed to run freestyle step: Deploy app with helmfile; caused by NonZeroExitCodeError: Container for step 
title: Deploy app with helmfile, step type: freestyle, operation: Freestyle step failed with exit code: 1                  

why

• in my experience, that always happens when a pod is failing
• basically helm --wait will wait until a successful rollout
• since the pod is failing, it's never successful, so it ends up failing after the timeout window (edited)
• start by inspecting the pods status / logs to see what's going on

Load Testing Scenarios

what

• Do not include such long code blocks (e.g. UTILITIES MODULE). Better to link to them. It makes the page less legible.

references

• http://docs.cloudposse.com/load-testing/load-testing-scenarios/

Improve Pagination

what

• Allow skipping to any page

why

• Natural navigation

Current pagination:

Prefer something more like this... (github)

https://docs.cloudposse.com/glossary/page/2/

Kubernetes Autoscaling

what

• How do we add resource scaling triggers based on custom metrics?

See #20 (asked by @Nuru)

Add OpenGraph and Twitter Meta Tags

what

• Add og:* and twitter:* tags

why

• Prettier share links

references

• https://discourse.gohugo.io/t/hugo-seo-social-partials/353/44
• https://gist.github.com/vietlq/d1c7ecfb20ce7beac4a7f4df746c797c
• https://code.luasoftware.com/tutorials/hugo/meta-desciption-open-graph-twitter-card-for-hugo/

Section Indexes Do Not Show Subsections

what

• Subsections are not included when listing all content in a section

why

• Expected behavior is that a list of subsections are presented

Implement Algolia Search

what

• Implement algolia instant search like the one on readme.io

why

• Default docdock search is insufficient

Monitoring Custom Metrics with Grafana

what

• Ability to view metrics/graphs/reports
• How do we add custom metrics to graphs?

See #20 (requested by @Nuru)

http://localhost:1313/development/12-factor-pattern/

Cloud Posse Developer Hub

Add AMP & Schema.org

what

• AMP
• schema.org

why

• SEO

AMP references

• https://www.ampproject.org/
• https://developers.google.com/amp/
• https://www.theverge.com/2018/3/8/17095078/google-amp-accelerated-mobile-page-announcement-standard-web-packaging-urls
• https://moz.com/blog/amp-digital-marketing-2018

schema.org references

• http://schema.org/docs/gs.html
• http://schema.org/docs/full.html
• https://en.wikipedia.org/wiki/JSON-LD

Hugo AMP and Structured Data references

• https://gohugo-amp.gohugohq.com/schema/
• https://gohugo-amp.gohugohq.com/
• https://themes.gohugo.io/gohugo-amp/
• https://themes.gohugo.io/amp/

Auto Expanding Code Blocks

what

• auto-expanding code blocks (e.g. https://gohugo.io/content-management/shortcodes/)
• use css (with transitions) to expand/contract code blocks with mouse over

why

• Our wide code blocks do not respect page margines which looks ugly, but is very practical since code is often very wide

Wrong font size for headers

what

• https://docs.cloudposse.com/geodesic/module/usage/with-terraform/#examples
• Example header looks smaller then it's child Provision CloudTrail with Terraform
• Check all subheaders, please

Implement SEO Enhancements

what

• Breadcrumb
• Sitelinks Searchbox
• Social Profile
• Corporate Contact
• Logo

references

• https://developers.google.com/search/docs/guides/search-gallery

`aws-vault` lacks usage examples

what

• how to use aws-vault exec
• how to use aws-vault --server
• .zshrc

https://docs.cloudposse.com/tools/aws-vault/

Icon Missing from First Section on Homepage

what

Document Github Authorized Keys

what

• Import docs from https://github.com/cloudposse/github-authorized-keys

why

• Needed to document how to setup terraform-aws-ec2-bastion

Add Support for GitHub Issues as Comments on Pages

what

• Allow users to comment on any page, which would create on the backend a github issue

why

• Provide an easy mechanism for contributions to pages
• Github Issues are a great way to track corrections/edits

how

• Great news, a JS widget for this already exists here: https://github.com/utterance/utterances

Duplicate Page Titles

what

• Google Webmaster Tools says that our titles are not unique

why

• I think our theme might not be correctly settign the <title/> tag for the pages

Embed Gitter Sidecar for Live Chat Support

what

• https://sidecar.gitter.im/

why

• Provide a lobby to chat and get real-time feedback

CI/CD of Documentation Portal

what

• Create docs project in prod.cloudposse.org
• Use CodeFresh pipeline
  • make build
  • aws s3 sync --acl public-read --delete --exact-timestamps public/ s3://...../
• Update badge in README.md

why

• Publish documentation

Document Secrets Management

what

• Ability to view or change secrets?
• How do we audit access and changes to secrets?
• Updating chamber secrets on console
• Updating chamber secrets on web
• Updating charts that use secrets

See #20 (by @Nuru)

Document Goofys Usage with Kubernetes

what

• Document how to use goofys as a sidecar container in kubernetes

why

• Useful for certain kinds of services that simple object storage but only work with POSIX-style filesystems

example

apiVersion: v1
kind: Pod
metadata:
  name: example
spec:
  restartPolicy: Never
  imagePullSecrets:
    - name: dockercfg
  volumes:
  - name: s3-mount
    emptyDir: {}

  containers:
  - name: nginx-container
    image: nginx
    volumeMounts:
    - mountPath: /data:slave
      name: s3-mount
      mountPropagation: Bidirectional      

  - name: goofys
    env:
    - name: MOUNT_DIR
      value: /vortex-artifacts
    - name: BUCKET
      value: eg-example-data
    - name: REGION
      value: us-west-2
    - name: DIR_MODE
      value: "0777"
    - name: FILE_MODE
      value: "0777"
    image: cloudposse/goofys
    imagePullPolicy: Always
    resources: {}
    securityContext:
      privileged: true
      runAsUser: 0
    terminationMessagePath: /dev/termination-log
    terminationMessagePolicy: File
    volumeMounts:
    - mountPath: /data:shared
      name: s3-mount
      mountPropagation: Bidirectional

Add Contributor Bio for Sarkis

what

• Add new page for contributors/sarkis-varozian

Drafts are not hidden from side bar

what

• Drafts should not appear in the left-sidebar

why

• Confusing documentation

Implement Hamburger Menus for Mobile

what

• Should display hamburger menu for mobile
• Should hide calendly link on mobile
• Use https://github.com/mac81/pure-drawer/

Add Support for Redirect Front Matter

what

• Add a redirect front matter parameter

why

• Support redirecting offsite. This is different that alias

example

<!DOCTYPE html>
<html>
  <head>
    <title>https://someothersite.com/posts/my-intended-url</title>
    <link rel="canonical" href="https://someothersite.com/posts/my-intended-url"/>
    <meta name="robots" content="noindex">
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <meta http-equiv="refresh" content="0; url=https://someothersite.com/posts/my-intended-url"/>
  </head>
</html>

related

• https://gohugo.io/content-management/urls/#how-hugo-aliases-work

Consider Adding Line Numbers to Code Blocks

what

• Prefix code blocks with line numbers

why

• Make it easier to reference lines of code

references

• https://www.sylvaindurand.org/using-css-to-add-line-numbering/
• Example: https://guides.emberjs.com/v2.12.0/tutorial/deploying/

GitHub Rate Limits Fail Builds

what

• Due to our heavy dependency on assets on GitHub, we're (probably) getting rate limited

why

• I think it's because the size of our documentation has increased so that now we reached the threshold

12-Factor Page

what

• Markdown formatting issues

• https://docs.cloudposse.com/glossary/12-factor/

Document Nginx-ingress + Redirects

what

• @Nuru asks how to setup up a redirect in nginx ingress

Convert from TOML to YAML Config

what

• Use config.yaml format rather than TOML

why

• We use YAML everywhere else
• We can use yq to manipulate YAML config
• There are known issues with TOML that are non-obvious: https://discourse.gohugo.io/t/ignore-a-directory/8880/4

Document Upgrading Kops Kubernetes Cluster

what

• Explain how to upgrade kops
• Explain how to upgrade kubernetes cluster

Fix Mobile Responsive Design

what

• Site is not mobile friendly (however, docdock is so something broke)

Search Links Broken when Pages Renamed

what

• Algolia will keep stale links

https://docs.cloudposse.com/kubernetes-backing-services/monitoring/prometheus-alerts-grafana/

development/12-factor-pattern/

Cloud Posse Developer Hub

http://localhost:1313/development/12-factor-pattern/

Invalidate CloudFlare Cache on Deployment

what

• Clear cache on deployment

why

• Serve fresh content

references

• http://www.davekopecek.com/cloudflare-command-line-cache-clear/

Add Chapter Links to Chapter Titles

what

• Add a link to chapter titles

why

• Make it easier to share content

examples

Highlight Current Chapter in Table of Contents

what

example: https://codefresh.io/docs/docs/configure-ci-cd-pipeline/push-image-to-a-docker-registry/

why

• Make it clear where you are in the documentation

Homepage Section Title Indention

what

• Titles have wrong indention

Fix ugly `hcl` code blocks

example

Add `include-code-block` shortcode

what

• should work like our code-block shortcode
• should include a source file

why

• inlining large chunks of code in the documentation is not maintainable
• no way to easily lint code blocks (e.g. terraform code)

example UI

{{% include-code-block src="/content/geodesic/examples/test.tf" language="hcl" title="Example Root Module" %}}

references

• https://gohugo.io/templates/files/#readfile-example-add-a-project-file-to-content
• https://gohugo.io/functions/readfile/

Cheat Sheet

what

• Document a cheat sheet for things like where we are storing secrets and how to change them, how to scale up and down or tweak auto-scaling, where our dashboards are, what the various repos you created are for

(requested by @Nuru from PopChest)

Document How to Run Pods on Masters

what

• Explain how to run pods on masters

why

• In rare cases, this is desirable

references

• https://github.com/cloudposse/geodesic/pull/135/files

Document How to Change Default Ingress 404/503 Pages

what

• document how to change the look/feel of k8s 404/503 pages

why

• Users may want to brand it

(Requested by @ballou88)