EPIC: Production-level documentation

[randomvariable]

trafficstars

/kind documentation /help

I've been going through documents for AWS Technical Baseline Reviews, and have drawn up this list of documentation that we should have to help end-users based on their checklist.

• [ ] Typical deployment with list of all resources
• [ ] List all deployment options (single-AZ, multi-AZ, multi-region)
• [ ] Expected time to complete deployment
• [ ] List skills / knowledge to complete deployment (familiarity with AWS, specific services etc...)
• [ ] Supported environment configurations (networking, DNS etc...)
• [ ] Architecture diagram using AWS simple icons, labelling where user data is stored
• [ ] Network diagram showing VPCs, subnets, security groups, NACLs, and ingress/egress mappings
• [ ] Integration points showing third-party assets (e.g. Kubernetes OCI registries)
• [ ] Links to IAM and IAM best practice documentation
• [ ] How to deploy without root privileges
• [ ] Prescriptive guidance on least privilege policies
• [ ] Clearly highlight public resources (like AMIs, clusterctl Github repos)
• [ ] Describe purpose and location of each key (EBS root volume encryption etc....)
• [ ] Document maintenance of AWS Secrets Manager
• [ ] Highight where sensitive data is stored (PVCs and etcd root volumes)
• [ ] List of all billable services, showing which are mandatory or optional
• [ ] Guidance for EC2 instance type and size selection
• [ ] Guidance for EBS volume type and size selection
• [X] Step by step instructions for typical deployment architecture
• [ ] Step-by-step deployment guide for maximising uptime and reliability
• [ ] Prescriptive guidance for testing and troubleshooting
• [ ] Step-by-step Instruitions on how to assess and monitor the health of the cluster and Cluster API
• [ ] Step-by-step instructions for restoring data from a backup
• [ ] Step-by-step instructions for recovery from instance failure
• [ ] Step-by-step instructions for recovery from AZ failure
• [ ] Documentation on managing AWS & K8s service limits to allow for disaster recovery
• [ ] Documented RTO and RPOs for deployments
• [ ] Step-by-step instructions for rotating credentials and cryptographic keys
• [ ] Prescriptive guidance for software patches and upgrades
• [ ] Prescriptive guidance for managing AWS service limits
• [ ] Step-by-step instructions on handling fault conditions
• [ ] Step-by-step instructions for recovery
• [ ] How to use externally provisioned ASGs via third-party services for both unmanaged and EKS
• [ ] How to run "airgapped"
• [ ] How to bootstrap with temporary credentials
• [ ] Diagnosing CloudFormation errors

[k8s-ci-robot]

@randomvariable: This request has been marked as needing help from a contributor.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed by commenting with the /remove-help command.

In response to this:

/kind documentation /help

I've been going through documents for AWS Technical Baseline Reviews, and have drawn up this list of documentation that we should have to help end-users based on their checklist.

• [ ] Typical deployment with list of all resources
• [ ] List all deployment options (single-AZ, multi-AZ, multi-region)
• [ ] Expected time to complete deployment
• [ ] List skills / knowledge to complete deployment (familiarity with AWS, specific services etc...)
• [ ] Supported environment configurations (networking, DNS etc...)
• [ ] Architecture diagram using AWS simple icons, labelling where user data is stored
• [ ] Network diagram showing VPCs, subnets, security groups, NACLs, and ingress/egress mappings
• [ ] Integration points showing third-party assets (e.g. Kubernetes OCI registries)
• [ ] Links to IAM and IAM best practice documentation
• [ ] How to deploy without root privileges
• [ ] Prescriptive guidance on least privilege policies
• [ ] Clearly highlight public resources (like AMIs, clusterctl Github repos)
• [ ] Describe purpose and location of each key (EBS root volume encryption etc....)
• [ ] Document maintenance of AWS Secrets Manager
• [ ] Highight where sensitive data is stored (PVCs and etcd root volumes)
• [ ] List of all billable services, showing which are mandatory or optional
• [ ] Guidance for EC2 instance type and size selection
• [ ] Guidance for EBS volume type and size selection
• [X] Step by step instructions for typical deployment architecture
• [ ] Step-by-step deployment guide for maximising uptime and reliability
• [ ] Prescriptive guidance for testing and troubleshooting
• [ ] Step-by-step Instruitions on how to assess and monitor the health of the cluster and Cluster API
• [ ] Step-by-step instructions for restoring data from a backup
• [ ] Step-by-step instructions for recovery from instance failure
• [ ] Step-by-step instructions for recovery from AZ failure
• [ ] Documentation on managing AWS & K8s service limits to allow for disaster recovery
• [ ] Documented RTO and RPOs for deployments
• [ ] Step-by-step instructions for rotating credentials and cryptographic keys
• [ ] Prescriptive guidance for software patches and upgrades
• [ ] Prescriptive guidance for managing AWS service limits
• [ ] Step-by-step instructions on handling fault conditions
• [ ] Step-by-step instructions for recovery
• [ ] How to use externally provisioned ASGs via third-party services for both unmanaged and EKS
• [ ] How to run "airgapped"
• [ ] How to bootstrap with temporary credentials
• [ ] Diagnosing CloudFormation errors

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[richardcase]

Great list @randomvariable. I can help with some of this.

[sftim]

Architecture diagram using AWS simple icons, labelling where user data is stored

For my part I'd also be OK with using eg https://github.com/kubernetes/community/tree/master/icons

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[richardcase]

/lifecycle frozen

[randomvariable]

@sfzylad , let's chat about this at some point too.

[randomvariable]

/priority important-longterm

[richardcase]

/remove-lifecycle frozen

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten