DOCSEARCHbyAlgolia
Submit Docs

decK Documentation

repository·main·Indexed 19 days ago

https://github.com/kong/deck

decK is a declarative configuration tool for Kong and Kong Enterprise (>= 0.35) that manages state via YAML files. It provides capabilities for exporting, importing, validating, and synchronizing configurations, as well as drift detection. The tool supports Kong Gateway (>= 1.x), Konnect Control Planes, and AI Gateway operations via the `ai` subcommand. Key features include parallel operations, multi-file management using selector tags, and integration with CI/CD pipelines.

Tokens
24.5K
Snippets
72
Records
98
Agent score
67%

What's inside decK

  1. What is decK and its core features?

    main

    decK is a tool for declarative configuration and drift detection for Kong. It is designed to be integrated into CI pipelines to automate configuration management.

    Core Capabilities:

    • Export: Back up existing Kong configuration to a YAML file.
    • Import: Populate Kong's database using an exported or hand-written YAML configuration.
    • Diff and Sync: Compare the configuration in a file against Kong's database to detect drifts and synchronize them.
    • Reverse Sync: Detect changes made directly in Kong that are missing from your configuration files.
    • Validation: Validate YAML files to catch configuration errors early.
    • Reset: Drop all entities in the Kong database.
    • Parallel Operations: Executes Admin API calls in parallel using multiple threads for faster synchronization.
    • Authentication: Supports injecting custom HTTP headers into requests to the Kong Admin API.
    • Multi-file Management: Allows splitting configuration into multiple logical files based on shared tags.

  2. How decK handles state files and the Admin API

    main

    decK manages two primary representations of Kong configuration:

    Local State Files

    When reading from a file (e.g., kong.yaml), decK unmarshals the YAML into a file.Content struct. This struct is hierarchical; for example, an FService struct contains not just the service definition, but also slices of FRoute (routes using that service) and FPlugins (plugins applied to it). This nesting allows decK to manage complex relationships defined in a single file.

    Admin API State

    When fetching the current state from Kong, decK retrieves a RawState. Unlike the file representation, RawState is flat and contains only the direct Go-Kong structs without relationship nesting. decK then builds a state.KongState using a memdb table to reconstruct these relationships, ensuring the Admin API state can be compared accurately against the hierarchical file state.

  3. Understand the decK command execution path

    main

    To understand how decK processes a command like deck sync, it is helpful to follow the lifecycle of the request through its core subsystems:

    1. Command Entry (cmd): The process starts in the cmd package (using Cobra/Viper). For example, sync.go invokes syncMain() in common.go.
    2. Building State: decK must reconcile two states:
      • Target State: Read from a local file (default kong.yaml) into a file.Content struct. This struct contains nested Go structures representing Kong entities and their relationships.
      • Current State: Fetched from the Kong Admin API via fetchCurrentState(). This is retrieved as a RawState (flat Go-Kong structs) and then transformed into a state.KongState (using a memdb table) to resolve relationships.
      • Normalization: The file data is transformed into a KongState using file.Get() so that both states exist in the same format.
    3. Comparing State: decK uses a diff.Syncer to compare the target and current states. The Solve() function determines the necessary CRUD (Create, Read, Update, Delete) operations by looping through entities to identify what needs to be added, updated, or removed.
    4. Updating Configuration: CRUD events are emitted to a channel and handled by consumers. These consumers execute the actual changes by calling the processor.Do() method, which uses a go-kong client to issue the appropriate HTTP calls to the Kong Admin API.

  4. Install decK on Windows

    main

    On Windows, you can download the binary from the GitHub release page or use PowerShell to download and extract the archive.

    $ curl -sL https://github.com/kong/deck/releases/download/v1.65.0/deck_1.65.0_windows_amd64.tar.gz -o deck.tar.gz
$ tar -xzvf deck.tar.gz

  6. Install decK on Linux

    main

    On Linux, you can install decK by downloading the binary archive from the GitHub releases page and moving the binary to your local bin directory. Alternatively, Debian or RPM archives are available on the release page.

    $ curl -sL https://github.com/kong/deck/releases/download/v1.65.0/deck_1.65.0_linux_amd64.tar.gz -o deck.tar.gz
$ tar -xf deck.tar.gz -C /tmp
$ sudo cp /tmp/deck /usr/local/bin/

  8. How to add a new entity to decK

    main

    To support a new Kong entity in decK, you must implement logic across several subsystems to handle state building, comparison, and execution. The process involves updating the following components:

    1. Diffing Logic (diff package)

    Implement per-entity functions to handle changes between current and target states:

    • syncer.createUpdate() and syncer.delete(): Add calls to your new entity functions here.
    • Entity-specific source file: Create a file in the diff package named after your entity.
    • deleteEntities(): Loops over current state entities and calls deleteEntity(). Note that deleteEntity() only performs a deletion if the entity is not found in the target state.
    • createUpdateEntities(): Performs the reverse, using entity.EqualWithOpts() to detect changes and emit events.
    • Post-processing: Implement functions to update the current state (adding or removing the entity) after an event succeeds.

    2. Dumping Logic (dump package)

    To support the dump command:

    • Call the corresponding go-kong List() functions.
    • Append the resulting structs to a slice to be included in the output.

    3. File State Building (file package)

    To allow the entity to be parsed from/to YAML files:

    • Statebuilder: Add logic to loop over entities in a file and add them to the raw state. If the entity is nested (e.g., credentials under a consumer), add the logic within the parent's handler function. If it is a top-level entity, add it to the build() function.
    • schema.go: Add new JSON schemas for (un)marshaling.
    • types.go: Define a new FEntity type (for top-level entities) or update an existing type (for nested entities).
    • writer.go: Add entity handlers to KongStateToFile(), ensuring you strip out unwanted content like timestamps and IDs.

    4. Execution Logic (solver package)

    To handle the actual API calls to Kong:

    • Implement functions that issue HTTP calls for the entity with necessary validation.
    • Register these functions for the entity name so the solver can process events with the corresponding Kind.

    5. State Management (state package)

    To manage the internal representation of the entity:

    • Database Schema: Add a go-memdb database schema and query functions.
    • CRUD Functions: Implement generic create/update/delete functions that manipulate rows (usually via ID or name).
    • Indexing: Use go-memdb indexers (like StringFieldIndexer or custom MethodIndexer) to allow efficient querying.
    • Type Definitions: Add the state type, method definitions, and type equality functions to state/types.go.

  9. Use selector tags to manage specific Kong entities

    main

    decK can use selector tags to identify and manage a subset of entities (Consumers, Consumer Groups, Routes, Services, or Partials) in Kong.

    Important Constraint: If you specify selector tags in your state file's info section, they must match the tags provided via the --select-tags CLI flag. decK requires that tags are specified consistently either via the flag or via the state file, but not both with different values.

  10. Manage RBAC resources with --rbac-resources-only

    main

    decK distinguishes between proxy configuration (Services, Routes, Plugins, etc.) and RBAC configuration (RBAC Roles).

    State files must consist entirely of one or the other. If your state file contains RBAC resources, you must use the --rbac-resources-only flag to manage them. If you attempt to run a command without this flag on a state file containing RBAC resources, decK will return an error.

  11. Sanitize Kong configuration during dump

    main

    When exporting configuration, you can use the --sanitize flag to protect sensitive information. This feature hashes passwords, keys, and other sensitive details in the output file.

    To ensure that the same sensitive data always results in the same hash (which is useful for maintaining consistency across environments), provide a specific value using the --sanitization-salt flag. If this flag is omitted, a random salt is used for each dump.

    # Dump a sanitized configuration with a fixed salt
deck gateway dump --sanitize --sanitization-salt "my-secret-salt" -o sanitized_config.yaml

  12. Konnect Client Initialization Logic

    main
    When operating in Konnect mode, decK initializes a kong.Client by resolving the Konnect Control Plane ID. The resulting client address is constructed using the pattern: {konnect_address}/v2/control-planes/{control_plane_id}/core-entities. This abstraction allows users to interact with Konnect as if it were a standard Kong instance, while decK manages the underlying Konnect-specific routing and authentication.