REST API, Repository Provisioning, Security Automation, Pagination, and Infrastructure-as-Code Patterns: Configuration, Design Choices, and Tradeoffs

1. From “script that works” to an operating model

Lesson 2 proved a small script can provision Nexus. Production automation adds harder questions: Who owns desired state? Who reviews changes? Which identity runs it? What happens when an operator changes the UI? How are secrets injected? Can a resource update in place? What happens when Nexus upgrades and a schema changes?

The same REST endpoint can be safe or dangerous depending on ownership, privilege, and reconciliation policy.

2. Imperative script versus declarative reconciliation

No approach removes the requirement to understand Nexus state. A provider that internally calls REST inherits the same API/version/authorization boundaries.

3. Bootstrap identity versus service identity

A common anti-pattern is putting the admin password into a CI variable and letting every repository job use it. Separate:

1. Bootstrap authority for rare establishment of administration/security objects.
2. Reconciliation authority scoped to resources and operations automation owns.
3. Publisher/consumer identity for data-plane access only.

Provisioning security may genuinely require elevated privileges; that does not justify granting them to the package publisher or every CI job.

4. Delete-and-recreate is not a generic update strategy

Repository identity connects to content, clients, privileges, groups, cleanup policies, routing, CI configuration, and audit expectations. Deleting a repository to change one field can trigger much more state change than intended.

5. API-generated configuration versus manual UI ownership

Define each field/resource as enforced, detect-only, human-owned, or ephemeral. A drift report must distinguish server defaults that changed after upgrade from a deliberate human edit. Normalize omitted/default fields carefully instead of producing noisy perpetual plans.

6. Desired state must not become a secret dump

repositories:
  - name: learner-api-hosted
    format: raw
    type: hosted
    online: true
    storage:
      blobStoreName: default
      strictContentTypeValidation: true
      writePolicy: ALLOW_ONCE
service_accounts:
  - userId: svc-learner-api
    roles: [learner-api-publisher]
    password_from_env: NEXUS_SVC_PASSWORD

The final field points to runtime secret injection; it is not the secret itself.

7. Provider/plugin versus direct REST

Evaluate higher-level tools with four questions: Does the provider model your exact Nexus release and field? How quickly does it support new formats/security APIs? Does its state contain sensitive values? What does it do when a resource is changed manually or cannot update in place?

When coverage is incomplete, direct REST can be clearer than hidden escape hatches. Conversely, a mature provider can offer plan/state/graph behavior your script lacks.

8. Error and retry policy is part of design

Do not retry every error. Timeouts and selected 5xx responses may justify bounded backoff only when the operation can be retried safely. A 400 should fail fast; 403 triggers privilege diagnosis; 409 triggers a fresh GET and conflict analysis. If POST times out, GET the deterministic resource before POSTing again.

9. Concurrency and shared ownership

Two reconcilers can read the same old state and race. Use one automation owner per resource set, external locking or CI concurrency controls where appropriate, and fresh state reads immediately before destructive actions.

10. Worked decision table

11. Version lifecycle: schema tests before rollout

Before upgrading Nexus, capture current OpenAPI, run contract tests against the target version, compare used resource models, and test the reconciler on a disposable clone. An API client generated for 3.95.2 is part of the upgrade compatibility surface; Chapter 27 expands the full upgrade process.

12. Knowledge check

13. Summary and next step

Safe IaC is an operating model: explicit ownership, least-privilege identities, in-place updates, deterministic drift handling, bounded retries, version contract tests, and evidence. Lesson 4 deliberately breaks these assumptions so you can diagnose automation failures.

Official references and version notes

• Sonatype: Automation / REST API — OpenAPI/Swagger location, API integration, and Jetty 12 URL-encoding requirements.
• Sonatype: Nexus Repository API Reference — current endpoint catalog and request/response models.
• Sonatype: Repositories API — generic and format/type-specific repository configuration endpoints.
• Sonatype: Components API — component list/get/upload/delete behavior and continuation tokens.
• Sonatype: Pagination — continuation-token iteration contract.
• Sonatype: Security Management API — users, roles, privileges, content selectors, LDAP/SAML/OIDC boundaries.
• Sonatype: Authentication — local/external authentication and automation identity boundaries.
• Sonatype: User Tokens — current self-hosted Pro entitlement and token behavior.
• Sonatype: System Requirements — Java/database/storage baseline.