Design decisions and FAQ

No. You don’t need to adopt the whole KongAirlines example. KongAirlines shows one approach and doesn’t define a required architecture. Choose a pattern that addresses your needs and adapt it to your existing engineering platform. You don’t need deployment credentials to read the public implementation.

In the KongAirlines example, the source of truth is the desired state in the owning repository. It includes the OpenAPI contracts, the transformation inputs, the kongctl manifests, and the committed generated decK configuration. The platform repository keeps the reviewed production Gateway copy. Live Konnect state helps you test a deployment. It doesn’t replace the reviewed desired state.

Service teams understand their APIs and keep ownership of the API lifecycle. They manage Catalog APIs, versions, specifications, and publications directly, including in production. The platform team owns shared infrastructure and production Gateway changes. A promotion PR governs the production traffic path and leaves Catalog ownership with the service team.

No. Namespaces and tags aren’t security boundaries in Konnect. Konnect RBAC determines what an identity is authorized to change. The kongctl namespaces and the decK select tags limit which desired-state resources a synchronization manages. Use authorization and reconciliation scoping together.

The example uses separate development and production Catalog namespaces because the stages synchronize independently. Development Gateway state uses tags that belong to each service. The platform synchronizes production as one reviewed aggregate.

No. The example gives service identities write access to the development Gateway and read access to the production control plane. Service identities have no write access to the production Gateway. The example uses broad Catalog API roles to keep the first setup simple. Those roles don’t isolate the Catalog APIs of one service team from another. Review and refine the permissions for your own resource boundaries.

Separate files and named resources make the differences between stages explicit, and the example doesn’t use branches as environments. The example also uses separate Catalog API entities, Dev Portals, and application authentication strategies for development and production. This is the implemented topology and no organization must copy it. Review it again as your needs and the supported Konnect capabilities change.

Use separate Catalog API entities when staging and production must select and promote their current contracts independently. The KongAirlines example implements this model for development and production. Each API is published to its environment’s Dev Portal and linked to its control plane. Compare the Bookings development manifest and production manifest.

Two Dev Portals alone don’t require separate Catalog APIs. Sharing one API is suitable when both Portals should expose the same specifications, current version, and runtime implementation. A Portal publication doesn’t select a specification version independently. Changing the shared API’s current version affects both Portals, and publishing its specifications to staging also makes them available through its production publication. Use separate APIs if unreleased specifications must stay out of the production Portal.

The example uses control-plane implementations with Access Control Enforcement (ACE). In the documented control-plane linking model, an API can link to only one control plane at a time. Separate entries let each environment select its current contract and manage application access independently.

Keep the contracts in one source repository and promote a reviewed release between environments. The example retains stable specifications as versioned files and selects the production release in its manifest. After platform review and production Gateway synchronization, the service workflow updates the production Catalog API and its publication from the promoted source commit. The development API remains available for subsequent changes. Follow the API delivery flow for the release and promotion sequence. The example’s beta naming and retention conventions are choices you can adapt.

Specification versions provide documentation history within an API. Selecting a specification in Dev Portal doesn’t switch the runtime environment or application registration. Manage registrations and credentials separately for staging and production; don’t assume that staging access grants production access.

The example treats released contracts as immutable and development versions as append-only. Reviewers can identify the contract that the team selected for production and inspect its generated configuration.

Development adds the new child version through a separate apply manifest and omits the versions collection from the sync manifest. Production explicitly retains released versions in its manifest. This design stops the synchronization from treating retained development history as stale state and deleting it. Retention is a policy of the example, and other version lifecycles are possible.

With kongctl 1.21 or later, a managed API can declare force_delete: true. This field authorizes updates that remove operations mapped to Access Control Enforcement (ACE) from the current specification of the API. The example enables the field on development and production APIs. This includes public APIs that link to control planes with ACE enabled.

The field doesn’t request deletion of the API and doesn’t bypass other validation. The authorization lasts as long as the field stays enabled. Set the field on the managed parent API. Do not set it on versions, external APIs, or file defaults. The field is an execution policy, and a dump of live Konnect state doesn’t infer it.

Declarative reconciliation selects the target version without a custom transition script. This authorization doesn’t change the version retention policy of the example.

Each service repository uses its own Konnect system account. The platform desired state assigns existing accounts to teams. Operators issue the tokens and put them in GitHub Environment secrets as part of the setup. A separate GitHub App credential opens the cross-repository promotion PRs and dispatches the service workflows.

Production Gateway jobs and production Catalog jobs have separate environment approvals because they have different owners and identities. The example keeps validation without credentials separate from automation that can write. Do not expose deployment or write credentials to untrusted PR code.

The platform owns the Key Auth strategies of Dev Portal for each stage. It also owns the global ACE plugin with an anonymous fallback. Operations in Flights and Destinations that are public can proceed without application credentials. Publications in Bookings and Customer select a Key Auth strategy.

Each protected Gateway Service also has an access guard that the service owns. The guard runs after ACE and rejects anonymous access. If a Service has both public and protected operations, scope the guard to the protected Routes. OpenAPI security declarations don’t configure these runtime policies.

Developers register applications, request API access, get approval, and generate keys in Dev Portal. Public documentation visibility doesn’t give access to protected operations.

No. The API key in the KongAirlines example identifies the registered application. It doesn’t identify a passenger or the developer who is signed in to Dev Portal.

The guard for protected Services uses kong.ctx.shared.ace.application_id from Gateway 3.16. It overwrites the X-KongAir-Account-ID header that goes to the upstream. It removes the legacy passenger header and the API key before it proxies the request. The service source shows fictional accounts that belong to that application ID. Key rotation doesn’t select another application.

Read the guard input before you adapt it. When you upgrade Gateway, make sure that the ACE context integration still works. A service that relies on an internal identity header needs a trusted boundary between the Gateway and the service. The delivery workflows don’t deploy or change the existing upstream service at api.kong-air.com. To test hosted end-to-end behavior, send requests through a running Gateway to that upstream service.

A control plane implementation lets ACE use the operations in the specification for access decisions. These decisions are independent of Gateway routing. A service-level implementation uses the relationships between Gateway Services and Routes as the access boundary. Choose the relationship that matches your authorization model.

When a synchronization fails, read the failed workflow and its plan before you retry. A completed Gateway deployment and a pending or failed Catalog deployment are separate results. The system doesn’t roll them back as one transaction. Keep the source commit and the reviewed artifact aligned during recovery. RBAC propagation can also delay access after a role change.

A successful run that makes no changes doesn’t test an operation-removing version transition or runtime authentication.