Conduktor Terraform Provider

Explore the docs »

Report Bug · Request Feature · Contact support

· ·

· ·

This repository contains the Conduktor Terraform provider, which defines Conduktor resources so that they can be deployed using Infrastructure as Code (IaC).

Warning

• The Conduktor Terraform provider is currently in Alpha.
• It does not support all Console and Gateway resources yet. See our resources roadmap.
• Let us know if you have feedback or wish to be a design partner.

Table of Contents

• Supported resources
• Install
• Usage/Examples
  • Provider authentication
    • API key
    • Admin credentials
• Development
  • Requirements
  • Install git hooks
  • Building The Provider
    • Build and install provider in local Terraform registry
  • Adding Dependencies
  • Codegen
  • Run acceptance tests
  • Misc
• Resources Roadmap
• Contributing
• License

Supported resources

• Console user
• Console group
• Kafka Clusters with Schema Registry
• Kafka Connect Server
• Generic ⚠️ This resource is experimental and should be used with care.

Install

Provider should be installed automatically with terraform init, but it's recommended to pin a specific version or range of versions using the following required_providers configuration :

terraform {
  required_providers {
    conduktor = {
        source = "conduktor/conduktor"
        version = "~> X.Y" # where X.Y is the current major version and minor version
    }
  }
}

Usage/Examples

# configure provider
provider "conduktor" {
  mode        = "console"
  base_url    = "http://localhost:8080"
  api_token   = "your-api-key" # can also use admin email/password to authenticate.
}

# register an external user bob with PLATFORM.userView permission
resource "conduktor_console_user_v2" "bob" {
  name = "[email protected]"
  spec {
    firstname = "Bob"
    lastname  = "Smith"
    permissions = [
      {
        permissions = [ "userView" ]
        resource_type = "PLATFORM"
      },
    ]
  }
}

# create a group with Bob as a member
resource "conduktor_console_group_v2" "qa" {
  name = "qa"
  spec {
    display_name                 = "QA team"
    description                  = "Quality Assurance team"
    members                      = [ conduktor_user_v2.bob.name ]
    permissions = [
      {
        resource_type = "PLATFORM"
        permissions   = ["userView", "clusterConnectionsManage"]
      }
    ]
  }
}

You can find more examples in this repository inside example directory.

Examples can also be found in provider reference documentation available either in docs directory or at registry.terraform.io/conduktor/conduktor

You can also check out our documentation for resources reference and provider usage.

Provider authentication

To use Conduktor Console API, the Terraform provider needs to authenticate against it.

For that we offer two possibilities:

API key

Use an already manually forged API key. See documentation to create one.

Using HCL api_token attribute

provider "conduktor" {
  api_token = "your-api-key"
}

Using environment variables CDK_API_TOKEN or CDK_API_KEY.

Admin credentials

Use local user (usually admin) credentials pair. This will login against the API and use an ephemeral access token to make API calls.

Using HCL admin_user/admin_password attributes

provider "conduktor" {
  admin_user     = "[email protected]"
  admin_password = "admin-password"
}

Using environment variables CDK_ADMIN_EMAIL or CDK_ADMIN_PASSWORD.

Either way be aware that API Key and admin credentials are sensitive data and should be stored and provided to Terraform properly.

Development

Requirements

• Terraform >= 1.0
• Go >= 1.23
• Docker with compose to run acceptance tests locally
• Git hooks to format/lint code before committing

Install git hooks

Please install the git hooks to ensure that the code is formatted correctly and pass linter check before committing.

Run make install-githooks to install the git hooks.

Building The Provider

1. Clone the repository
2. Enter the repository directory
3. Build the provider using the Go install command:

go install

Build and install provider in local Terraform registry

Will build and install terraform provider locally in ~/.terraform.d/plugins directory. Local provider version is set on VERSION variable of GNUmakefile

VERSION=0.0.1 make deploy-locally

It can then be used on terraform recipe like

terraform {
  required_providers {
    conduktor = {
      source  = "terraform.local/conduktor/conduktor" # local provider
      version = ">= 0.0.1"                            # latest version found locally in the plugin cache.
    }
  }
}

Adding Dependencies

This provider uses Go modules. Please see the Go documentation for the most up to date information about using Go modules.

To add a new dependency github.com/author/dependency to your Terraform provider:

go get github.com/author/dependency
go mod tidy

Then commit the changes to go.mod and go.sum.

Codegen

The project uses different codegen tool to generate source files.

Documentation in docs folder is generated using tfplugindocs

Terraform schema definition in schema module are generated using tfplugingen-framework from currently manually maintained code spec json file.

Run acceptance tests

# Optional
export CDK_LICENSE="your_license_here"
make testacc

This action will start a testing environment using Docker Compose and run all acceptance tests against it. Test environment is destroyed at the end.

You can also start/stop environment and run tests in separate actions using make start_test_env / make test / make clean.

Misc

make generate   # run go generate
make build      # run build
make go-fmt     # run go fmt on the project
make go-lint    # run golangci-lint linter

Resources Roadmap

Future versions of the Conduktor Terraform provider will evolve to support more resources.

Need a resource to unblock a use case? Feedback to the Product team directly.

We are currently reviewing the following resources:

1. Console resources:

• KsqlDBCluster
• Alert

2. Kafka resources:

• Topic
• Subject
• Connector

3. Self-service resources:

• Application
• ApplicationInstance
• TopicPolicy
• ApplicationInstancePermission
• ApplicationGroup

4. Gateway resources:

• Interceptor
• GatewayServiceAccount
• GatewayGroup
• ConcentrationRule
• VirtualCluster
• AliasTopic

Note

This list is not exhaustive and can change depending on requests and needs.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.