Setup Java Spring Boot Platform

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Generates the OpenTofu (Terraform-compatible) configuration that deploys a Spring Boot service, derived from the technologies the service actually uses and the cloud recorded in its stack manifest.

Purpose

iru-setup-java-springboot-platform is governed by five rules, each of which shapes what it writes:

  • Managed services over self-packaged containers. The compose stack from Setup Java Spring Boot Testcontainers exists for local development and integration tests; deployed environments use the provider’s managed offering, because backups, failover, patching, and encryption-at-rest are the actual work and running them yourself is a permanent cost.

  • No secret in any file — not in a .tf, not in a .tfvars, not in a default. Secrets are created empty in the provider’s secret manager, with lifecycle { ignore_changes } on the value so a later apply never reverts a rotated secret, and populated out-of-band.

  • Remote, encrypted, locked state, because state contains resource attributes that are effectively secrets.

  • Keyless CI authentication via GitHub OIDC, with the trust policy scoped to the repository and the environment — a wildcard subject would let any branch deploy to production.

  • Nothing is applied. The skill writes configuration and runs validate (and plan only on request), because every apply costs money.

A substantial part of its value is the compatibility caveats it raises rather than papering over: DocumentDB is not MongoDB enough for Spring Data plus Flamingock, Neptune is not Neo4j, Amazon OpenSearch has diverged from Elasticsearch, Cloud SQL for MySQL is not a true MariaDB, MSK ships no managed schema registry (so AVRO needs Glue Schema Registry or Confluent Cloud), gRPC needs the load balancer’s protocol set to HTTP/2, and a Cloud Run service cannot reach a private Cloud SQL or Memorystore instance without a Serverless VPC Access connector. Where the right answer is a third-party managed service (MongoDB Atlas, Couchbase Capella, Neo4j Aura, Qdrant Cloud, Elastic or Confluent Cloud), it says so and notes that each needs its own account, billing, and provider credential.

The skill announces whether it is generating infra/ from scratch or updating an existing one (listing the modules and envs/* found) and never touches a .tfstate. For each existing file group it owns (per module, per environment, the backend configuration) it warns and asks Update (fill gaps) (Recommended) / Keep as is / Replace, unless on-existing pre-answers. Replace can produce a destructive plan against live infrastructure (renamed addresses mean destroy-and-recreate), so it is offered only with that warning and needs an explicit second confirmation for any environment with remote state; an on-existing: replace from args is treated as Update for those environments, so a scripted run can never replace live-resource configuration unattended.

Rolling deployments (optional)

When the manifest’s deploy.rolling.enabled is true (or rolling: yes arrives in args), the skill also creates the infrastructure for a staged rollout, following one design: the workflow drives the traffic shifting and the rollout state lives in the cloud, so promote.yml is stateless. OpenTofu creates the capability to hold two versions and split traffic between them but never the split itself: live weights, traffic and step are in lifecycle { ignore_changes }, so an unrelated tofu apply cannot reset a rollout in flight, and new versions always deploy at 0 % traffic. Strategy rolling has no second environment and uses the runtime’s native rolling update with a weaker rollback.

Runtime What is generated

ECS Fargate

Blue and green target groups with identical health checks and two ECS services (one per slot); a weighted forward action on the production ALB listener plus a test listener that points at the green group; CloudWatch alarms (5xx rate, p95 response time, unhealthy hosts) as the metric gate; and the deploy role’s extra, scoped ELB, CloudWatch and ECS permissions. An ALB is required: if the service is exposed any other way the skill flags it and stops rather than generate a canary that cannot split traffic. ECS’s native blue/green deployment type was checked and documented as the alternative for advance: auto only.

Cloud Run

An explicit traffic block pinned to the stable revision (new revisions get 0 %), a revision tag that provides the candidate URL, a Cloud Monitoring alert policy, and a deploy service account scoped to the service rather than the project.

EKS / GKE Autopilot

The Argo Rollouts controller (installed with a pinned Helm release, or verified as a prerequisite; Flagger is documented but not generated), the Deployment turned into an Argo Rollout whose canary steps start with setWeight: 0 then an indefinite pause, a Prometheus AnalysisTemplate, and namespace-scoped RBAC for the deploy identity.

Every environment’s outputs.tf then also exposes rollout_candidate_url, rollout_gate, and per runtime rollout_alarm_names, rollout_target_groups or rollout_name, which the workflows consume. With rolling absent or disabled nothing in this skill changes. See Spring Boot Rolling Deployments.

Purpose group

Spring Boot Service Bootstrap

Plugin

Shipped by the iru-springboot plugin of the ai-catalog marketplace (install with /plugin install iru-springboot@ai-catalog; see Plugins).

Invocation

/iru-setup-java-springboot-platform

Inputs

Argument Required Description Default

stack-file

No

args key: value line giving the manifest path. Read for the target cloud, the database engines, caches, messaging, observability, dynamic configuration, and which API surfaces the service exposes — that determines what infrastructure is needed.

springboot-stack.yml at the repository root

mode

No

args key: value line, new or existing. Informational only: it never means "update silently".

None

rolling, deployment-strategy, advance, steps, bake-minutes

No

args key: value lines: rolling is yes/no, deployment-strategy is rolling/blue-green/canary/linear, advance is auto/manual/hybrid, steps a comma list of percentages, bake-minutes a number. The manifest’s deploy.rolling block (enabled, strategy, advance, steps, bakeMinutes) is the source of truth when stack-file is given; the lines apply when there is no block or the caller passes them explicitly.

Rolling disabled

on-existing

No

args key: value line, ask, keep, update or replace, pre-answering the per-group Update / Keep as is / Replace question. replace is downgraded to Update for environments that have remote state.

ask

Environments

Yes

Which to generate. Each gets its own directory and its own state file, so a dev mistake can’t reach prod.

dev, staging, prod offered as the common set

Region, and multi-AZ for production

Yes

Per environment. Multi-AZ roughly doubles managed-database cost, so it is asked rather than assumed.

None

Sizing per environment

Yes

Replica min/max, CPU, and memory, plus the intended JVM heap — container memory must exceed heap plus metaspace plus native overhead, or the container gets OOM-killed.

Starting points offered (1 vCPU / 1–2 GiB, 2 replicas for prod)

Compute runtime

Yes

AskUserQuestion: ECS Fargate or EKS on AWS; Cloud Run or GKE Autopilot on Google Cloud. If the manifest’s dynamic configuration is kubernetes and a non-Kubernetes runtime is picked, the contradiction is flagged for the user to resolve.

Fargate / Cloud Run recommended

Existing versus new infrastructure

Yes

Asked per database, cache, and Kafka cluster: create it here, or reference an existing one via a data source and an identifier variable. Teams commonly share one cluster across services.

None

Public exposure, domain, DNS zone

Yes

Whether the service is internet-facing; if so the domain name and whether the zone already exists. TLS comes from ACM or Google-managed certificates.

None

State backend

Yes

The S3 + DynamoDB or GCS backend to use. If none exists, a separate infra/bootstrap/ configuration is generated to create just the backend — the one chicken-and-egg step.

None

Cost acknowledgement

Yes

Explicit confirmation, after naming the resources that bill continuously regardless of traffic (managed databases, NAT gateways, load balancers, Kafka clusters, provisioned OpenSearch).

None — must be confirmed

Outputs

  • A report stating whether infra/ was generated from scratch or updated, and per file group the action taken (created / updated / replaced / kept as is) with each gap left in a kept group. It also warns that when the manifest’s ci.enabled is false no deploy/undeploy workflow exists, so every tofu apply/tofu destroy is a manual run, deletion-protection advice applies to whoever runs it, and the CI OIDC identity is not needed until workflows are added.

  • infra/README.md — the bootstrap order, what every variable means and its blast radius, how to destroy an environment safely, what has deletion protection on purpose, and every step OpenTofu cannot perform with concrete instructions: domain registration or subdomain delegation, populating each secret’s value, the third-party accounts and provider credentials needed, the schema registry’s compatibility mode, quota increases, and SSO/OAuth provider configuration.

  • infra/modules/ — reusable modules for network, the service runtime, one per database engine, cache, Kafka, observability, and DNS, with no environment-specific literals.

  • infra/envs/<env>/ — thin per-environment directories (provider, backend, module calls, values) with one state file each, outputs.tf exposing endpoints and secret names, and documented .tfvars.example files.

  • infra/bootstrap/ — only when the state backend must be created.

  • The OIDC deployment role or service account, container registry with an immutable-tag policy and untagged-image expiry, the compute service with actuator-matching health probes and graceful-shutdown period, empty secrets with scoped IAM, log groups with an explicit retention period, and the managed metrics target.

  • Pinned required_version and required_providers constraints, with .terraform.lock.hcl committed.

  • Only when rolling deployments are enabled: the rollout resources per runtime (second target group and weighted listener with test listener, alarms, Cloud Run traffic pin and tag, or Argo Rollouts, Rollout and AnalysisTemplate), the rollout_* outputs in every environment, and a rolling-prerequisites section in infra/README.md (an ALB for ECS, Prometheus scraping for Kubernetes, thresholds to tune, the Argo controller, a candidate URL reachable from CI runners, the roughly doubled compute during a rollout, and how to inspect or reset the cloud-side split by hand). The report states whether rolling is enabled or disabled, the resources, the outputs, the design decision and the prerequisites.

Execution flow

flowchart TD A["Start /iru-setup-java-springboot-platform"] --> B["Step 0: Read the manifest and args;\ncheck for tofu and an existing infra/"] B -- infra/ exists --> C["Announce update; per file group ask\nUpdate fill gaps / Keep as is / Replace\n(or apply on-existing); never touch .tfstate;\nnever replace live-resource .tf unattended"] B --> D["Step 1: Ask what cannot be inferred —\nenvironments, region, sizing, runtime,\nnew vs existing, exposure, state backend"] C --> D D -- kubernetes config + non-Kubernetes runtime --> E["Flag the contradiction;\nuser resolves it"] E --> D D --> F["Cost acknowledgement"] F --> G["Step 2: Scaffold infra/ —\nmodules/ and one envs/ dir per environment"] G --> H["Step 3: Generate per cloud, preferring\nmanaged services; raise every\ncompatibility caveat;\nwhen rolling is enabled also the rollout\nresources and rollout outputs"] H --> I["Step 4: Wire the service to its dependencies —\nendpoints, secret references, network path, IAM"] I --> J["Step 5: Write infra/README.md\nincluding every manual step"] J --> K["Step 6: tofu init -backend=false,\nvalidate, fmt — never apply;\nwhen rolling, check ignore_changes\non every weight and traffic attribute"] K -- schema error --> L["Fix against the provider docs"] L --> K K --> M["Step 7: Report actions per group, resources,\ncaveats, secrets to populate, manual steps"]

Dependencies

Invokes

None. It reads springboot-stack.yml and the Spring profile files (so generated environment-variable names match the placeholders already referenced there), and writes OpenTofu configuration.

Invoked by

Also runs standalone (/iru-setup-java-springboot-platform).

Related: Spring Boot Rolling Deployments — the skill that enables, disables and operates rolling deployments, and whose workflows consume the rollout_* outputs this skill exposes.

Related agents

None — this skill runs its own tofu validation directly rather than delegating, since validate output is short.

Source

SKILL.md on GitHub — the file this page was generated from.