Answer by mikyll98 for How to Upload a New Certificate to Kong Using decK?

When you use the declarative configuration, you must provide the ID along with certificate specifications.

Example:

certificates:  - id: "my-certificate"    cert: |      -----BEGIN CERTIFICATE-----      ...your certificate content...      -----END CERTIFICATE-----    key: |      -----BEGIN RSA PRIVATE KEY-----      ...your key content...      -----END RSA PRIVATE KEY-----    snis:      - example.local    tags:      - example

The same happens for routes, but they can be identified by their name as well, and that's why you don't actually need to specify the ID.

The reason to this is that the Kong declarative configuration is a sort of equivalent of the PUT method, not the POST.

According to REST architectural style, the POST is used to create a new resource, while PUT is used to update a resource (or create it if it doesn't already exist).

For this reason, when you send a HTTP request to Admin API /certificates endpoint - assuming the request succeeds:

• if you send a POST, the server (Kong) takes full responsibility for the resource creation and you get back a response containing the ID;
• if you send a PUT, you're required to include the ID in the URL, because you, as a client, take some responsibility in resource creation (typically because you might need to reference this resource somewhere else).

Since the declarative configuration (via YAML) describes the "state of the system" explicitly, completely and persistently, it needs the explicit ID of the resource. And that is understandable for a series of reasons:

• operation idempotency - applying the same configuration repeatedly results in the same state (i.e. consistent deployments);
• stable references - since you know the ID a priori, you can reference this resource by using the always-the-same, static ID;
• explicit control (and management) - needed to enable, for example, fine-grained configuration and versioning;
• and, according to my personal point of view, because it wouldn't make sense otherwise - suppose you didn't need to provide the ID in declarative configuration. How would Kong handle the resource creation? It would assign arbitrary IDs and you wouldn't have any mean to tell two different resources of the same type (certificates in this example) apart unambiguously and unequivocally, before their creation. That would break any kind of declarative configuration purpose.