Cloud Platform Documentation index

Cloud Platform Team Charter #

Platform Definition #

A discipline which involves doing whatever it takes to build, maintain, and provide a curated platform experience for the communities using it.

Successful Platform Experience Characteristics #

  1. Clear Boundaries and Responsibilities

    • avoid the blame games and hot potatoes.

  2. Self Service and Automation:

    • clearly defined interfaces, docs, and processes.
      • ex. Wiki explaining use of Terraform. Example templates. Intro sessions to demonstrate advantages.
    • avoid death by 1000 tickets/requests.

  3. Flexible and Evolvable:

    • adaptable to different communities.
      • no one size fits all for everyone.
      • guardrails and guides (templates and docs) not heavy handed concrete process.
    • avoid rogue teams creating anti-patterns or bypassing platform guidelines.

  4. Reliable and caters for Day 2 operations:

    • avoid developers creating their own solutions and becoming a bottleneck.

Goal #

Create an internal developer platform and a reference architecture/blueprint for onboarding teams to an agreed upon department standard and to also remove platform toil for developers so they can do what they do best.

Be a Service, don’t just provide one #

  1. Make teams independent of you, not dependent on you.

    • allow the tools and docs we build empower them to help themselves.
      • (ex. AWS shared responsibility model)
    • Favor automation and API driven interactions.
      • onboarding
      • Terraform modules, templates, and examples.
    • Documentation
      • In-tool help and reference Examples.

  2. Promote Freedom over Autonomy: (freedom within agreed boundaries and autonomy is unrestrained chaos “self rule”)

    • establish ground rules
      • single cloud vs multi cloud
      • stable vs latest
    • choice over “anything goes”
      • tech stacks
      • ecosystems (Terraform, k8s, Azure container services, functions)
      • templated designs or blueprints

  3. Be a Role Model, Walk the Talk:

    • Eat your own dogfood: debug and work through the process on our own first.
      • tooling
      • testing against reference implementations
    • Offer internal “Professional Services”
      • workshops, pairing, embed in team for a time.
    • Platform evangelist/advocate
      • promote good practices

  4. Respect and Recognize Community Differences:

    • Adapt Ways of working for diff communities
      • team structures and interaction modes.

Benefits of infrastructure as code #

  • Promotes auditing by making it easier to trace what was deployed, when, and how. (In other words, it improves traceability.)
  • Provides consistent environments from release to release.
  • Greater consistency across development, test, and production environments.
  • Automates scale-up and scale-out processes.
  • Allows configurations to be version-controlled.
  • Provides code review and unit-testing capabilities to help manage infrastructure changes.
  • Uses immutable service processes, meaning if a change is needed to an environment, a new service is deployed, and the old one was taken down; it isn’t updated.
  • Allows blue/green deployments. This release methodology minimizes downtime, where two identical environments exist—one is live, and the other isn’t. Updates are applied to the server that isn’t live. When testing is verified and complete, it’s swapped with the different live servers. It becomes the new live environment, and the previous live environment is no longer the live. This methodology is also referred to as A/B deployments.
  • Treats infrastructure as a flexible resource that can be provisioned, de-provisioned, and reprovisioned as and when needed.

How to Contribute to this Site #

Software to install #

  1. Install hugo cli HUGO
  2. Request access to HHS GitHub Org if do not have it
  3. Request access to our Cloud Docs repo: pltf-book-docs
  4. Clone the repo
  5. Request access to the docs site itself Cloud Platform Docs

How to add content #

  1. Add your markdown files in current or new folders. See examples for how to build folder structure
  2. In the top level of the repo on your local computer, run hugo to render site locally. Fix any errors you may see returned
  3. push to remote GitHub repo
  4. Allow CI/CD to run in GitHub repo
  5. Verify changes Cloud Platform Docs

References #

Edit this page