Platform Onboarding Playbook: Terraform + Kubernetes Starter Template and Checklist for New Service Teams

Overview

A good platform engineering workflow separates reusable platform decisions from service-specific configuration. The platform team should provide tested building blocks for infrastructure, deployment, security, and observability. The service team should supply the application image, runtime settings, ownership details, and service-level expectations.

The examples below assume a service is deployed to Kubernetes and its supporting cloud resources are managed with Terraform. Adapt names, providers, module interfaces, namespaces, and CI systems to your environment. Pin versions in the repository rather than copying unreviewed examples into production.

A practical starter repository can contain the following:

• infra/ for Terraform configuration and environment inputs.
• deploy/ for Kubernetes manifests or Helm values.
• .ci/ for validation, image build, security checks, and deployment jobs.
• docs/ for ownership, dependencies, rollback steps, and operational notes.

Before implementation, define the service contract: who owns the service, which environment it targets, what data it accesses, how it is exposed, and what happens when the deployment fails. This prevents infrastructure configuration from becoming a substitute for missing operational decisions.

Checklist by scenario

1. New service with no existing cloud resources

1. Record the service name, repository, owning team, escalation path, and environment list.
2. Choose a naming convention for projects, accounts, resource groups, namespaces, labels, and tags.
3. Use a reviewed Terraform module for network access, identity, storage, databases, queues, or other required dependencies.
4. Define provider and module versions in the Terraform configuration and commit the lock file where appropriate.
5. Separate plan and apply permissions. Pull requests should produce a reviewable plan; production changes should require an explicit approval path.
6. Create the Kubernetes namespace, service account, resource requests, health probes, and network policy according to platform standards.
7. Build the container through CI, scan it according to your organization’s security process, and deploy an immutable image reference rather than a floating tag.
8. Add logs, metrics, alerts, and a basic runbook before the first production release.

2. Existing service moving onto a shared platform

1. Inventory current cloud resources, secrets, DNS records, endpoints, scheduled jobs, and external dependencies.
2. Decide which resources will be imported, recreated, or left under their current management boundary.
3. Compare current runtime behavior with the standard deployment profile, including ports, probes, shutdown handling, storage, and autoscaling.
4. Test configuration precedence. Document whether values come from Helm values, Kubernetes Secrets, an external secret manager, or environment-specific overlays.
5. Run the service in a non-production namespace with production-like dependencies where safe.
6. Prepare a migration and rollback plan that identifies data compatibility, traffic switching, and the point at which reversal is no longer safe.

3. Service requiring a database or sensitive credentials

1. Define the database lifecycle separately from the application lifecycle unless the platform explicitly supports a shared pattern.
2. Grant the workload only the identity permissions it needs, preferably through a dedicated service account or workload identity.
3. Keep secret values out of Terraform variables, manifests, logs, pull requests, and CI output. Store references or encrypted values using the organization’s approved mechanism.
4. Test rotation before production. Confirm that the application can reload or safely restart when credentials change.
5. Document backup, restore, schema migration, retention, and data deletion responsibilities.

For a more detailed operational review, use the secrets rotation checklist for cloud, CI/CD, and Kubernetes workloads.

4. Minimum CI/CD starter workflow

A reusable pipeline should fail early and make each promotion traceable. A typical sequence is:

validate -> test -> build image -> scan -> terraform plan
        -> publish artifact -> deploy to non-production -> verify -> approve -> promote

Keep deployment configuration versioned with the application or in a clearly connected configuration repository. Include a dry-run or manifest validation step, and make the deployed commit, image digest, configuration revision, and approver visible in the release record. The DevSecOps pipeline checklist can help identify security controls that belong at each stage.

What to double-check

Before approving the starter template, create a compatibility matrix that records the versions actually tested together. Do not treat it as a promise that every combination is supported.

Also double-check defaults. A default namespace, public load balancer, broad identity policy, unbounded resource request, or missing readiness probe can turn a convenient template into an operational risk. Review rendered Kubernetes output rather than only the source values. For broader manifest and rollout checks, see the Kubernetes deployment checklist.

Finally, confirm that the service is observable. Define an owner for alerts, identify a useful health signal, and document what action an alert should trigger. Reliability targets and error budgets are useful inputs when deciding whether a new service has enough operational coverage; the SRE error budget guide provides a framework for that discussion.

Common mistakes

• Copying a template without understanding its boundaries. A starter module should explain what it creates, what it assumes, and what it deliberately leaves to the service team.
• Using mutable image tags. A tag such as latest makes rollback and audit work harder. Prefer a digest or another immutable release identifier.
• Mixing infrastructure and application ownership. The platform team may own the module and cluster capability, while the service team owns service-specific inputs and runtime behavior. Make that boundary explicit.
• Applying Terraform from an unreviewed local machine. Use a consistent state backend, locked state operations, reviewed plans, and controlled credentials.
• Putting secrets in values files. Even private repositories and masked logs are not a complete secret-management strategy.
• Skipping failure testing. Test failed health checks, unavailable dependencies, rejected deployments, expired credentials, and rollback procedures before relying on the workflow.
• Allowing version drift. Unpinned providers, charts, actions, and base images can change the result of a previously successful pipeline.
• Measuring platform success only by deployment speed. Also track repeatability, rollback clarity, ownership, security findings, and the number of manual exceptions required.

For infrastructure-specific review, compare the template with established Terraform best practices for scalable cloud infrastructure. If the service exposes an API, document how engineers test it during onboarding; the API testing tools comparison covers several workable approaches.

When to revisit

Use this playbook at every new service rollout, but also revisit the starter repository and compatibility matrix on a regular maintenance cycle. A quarterly review is a practical baseline for checking pinned Terraform providers, module revisions, Helm charts, Kubernetes API usage, CI actions, base images, and security controls. Review sooner after a major upstream release, a deprecation notice, a failed upgrade, or a security advisory affecting a dependency.

Before seasonal planning or a period of increased delivery activity, ask:

• Can a new team create a service without platform engineers manually editing every file?
• Are the documented versions still tested together?
• Do CI credentials and runtime identities have only the required access?
• Can the team demonstrate deployment verification and rollback?
• Have recent incidents produced updates to the template, checklist, or runbook?

After each onboarding, capture one or two concrete improvements rather than expanding the template indefinitely. Remove obsolete options, clarify confusing defaults, and add a troubleshooting note for any failure that another team is likely to encounter. Keep a small changelog with the template so service teams can see what changed before copying a newer version.

For the next service rollout, copy the current starter repository, pin the tested versions, complete the scenario that matches your service, run the compatibility checks, and obtain explicit review from both the platform and service owners. That routine turns onboarding from an informal handoff into a repeatable platform engineering workflow.