Deploy Konnect Reference Platform

For most use cases, a single Konnect organization is sufficient. However, you may determine that your requirements include multiple Konnect organizations which the reference platform can support.

The FAQ page provides guidance on Konnect Organization design. If you choose to use multiple Konnect Organizations, the instructions pertaining to organizations in this guide will need to be repeated for each one you wish to add to the reference platform.

Create (if necessary) a new Konnect Organization and sign in

The Konnect Orchestrator (aka “orchestrator” or koctl) provides commands you can use to setup the reference platform in your own engineering environment. koctl is also ran within the APIOps workflows and creates and manages resource configurations within your Konnect Organization via APIs. In order to authorize the tool, use the following steps to create a system account with Organization Admin permissions:

1. From the Konnect web console, under Organization->System Accounts, create a new System Account named konnect-orchestrator
2. Add the konnect-orchestrator system account to the Organization Admin team
3. Use the Manage Tokens feature to generate a new access token for the konnect-orchestrator system account and securely save the token secret

Regardless of the number of Konnect Organizations used, the reference platform operates around a single Platform Team git repository. This repository will contain copies of the development teams API specifications, APIOps workflows, and other configurations that the orchestrator will manage.

From the GitHub web console, create (if necessary) a platform GitHub repository in your GitHub organization. An example repository can be found in the KongAirlines GitHub organization.

While we refer to this repository as the platform repository, the repository name on GitHub is arbitrary. The Konnect Orchestrator will file PRs to this repository under the .github/workflows and konnect sub-directories. You can use an existing repository as long as PRs with changes to these locations is acceptable.

The orchestrator requires specific access to the platform repository in order to facilitate the reference platform features. In order to authorize the orchestrator, you need to create a GitHub access token with the proper permissions.

1. From the GitHub web console, navigate to your profile menu, then Settings -> Developer Settings -> Personal access tokens
2. Create a new Fine-grained token and give the token a name that indicates it’s relationship to the orchestrator (e.g. platform-konnect-orchestrator)
3. Select the GitHub organization that owns the platform repository you created in the previous step and set appropriate token expiration
4. Under Repository access, choose Only select repositories and choose the platform repository.

5. Under Repository permissions, select all of the following permissions:

   Repository Permission	Access	Description
   Actions	Read & Write	Required to create and manage GitHub Actions
   Contents	Read & Write	Required to write declarative configuration files to the repository
   Pull requests	Read & Write	Required to file pull requests for all proposed code file changes
   Secrets	Read & Write	Required to write secrets (the orchestrator cannot read secret values from the repository)
   Workflows	Read & Write	Required to create and manage GitHub action workflows for APIOps

6. Once the token is generated, securely save the token secret

The orchestrator provides an init command to initialize the platform GitHub repository for you. The command will prompt you for the platform team GitHub repository URL and the GitHub token created previously.

1. Run the init command from your shell:

    koctl init
   

   Use the Tab key to navigate through the prompts and enter the required information

2. Enter the GitHub URL for the platform repository you created previously (the URL should be in the format https://github.com/<org>/<repo>)

3. Enter the GitHub token secret you created in the previous step

4. Tab onto the Go! button and koctl will proceed with initializing the repository by filing a PR containing the necessary changes to initialize the repository to participate in the platform

Once the koctl init command has completed, you will see a message indicating that a PR has been filed to the platform repository, including a link directly to the PR. The PR will have the following title: [Konnect Orchestrator] - Init Platform.

Open the PR in the GitHub web console and review the changes. Once satisfied with the changes, merge the PR into the main branch of the repository. You now have a platform repository that is ready to be used with the reference platform including GitHub actions that can facilitate the APIOps workflows and other configurations to support API delivery and governance.

As described earlier, the reference platform can support one or more Konnect Organizations. Generally a single organization design is sufficient, and you will only need to run the following instructions once. But if you wish to add multiple organizations, run these steps for each one you wish to support.

koctl provides a command to add a new Konnect Organization to the platform repository. Run the following and follow the prompts to provide the necessary information.

1. Run the add organization command from your shell:

    koctl add organization
   

2. Enter the URL of the platform repository you created in the previous steps
3. Enter the GitHub token secret you created in the previous steps
4. Enter the name of the Konnect Organization. This can be any name you choose but you should choose one that clearly relates to the name of the organization within Konnect
5. Enter the Konnect token you created earlier for the konnect-orchestrator system account
6. Once you have entered the necessary information, select the Go! button and the koctl tool will proceed with adding a PR that sets up the organization within the platform repository

Once the koctl add organization command has completed, you will see a message indicating that a PR has been filed to the platform repository, including a link directly to the PR. The PR will have the following title: [Konnect Orchestrator] - Add <org-name> Organization.

Open the PR in the GitHub web console and review the changes. Once satisfied with the changes, merge the PR into the main branch of the repository.

You have now added your Konnect to the platform repository and the APIOps workflows will initiate the necessary steps to prepare your Konnect Organization for use with the reference platform.

The reference platform includes a web-based self service tool that can be used to onboard your development teams and their services. Once this tool is configured and ran, you (or your development teams) can use it to add teams and service applications to the platform.

The self service tool requires additional GitHub security configuration because it uses OAuth to allow users to sign in with their GitHub accounts to browse and select their service repositories.

1. From the GitHub web console, navigate to your profile menu, then Settings -> Developer Settings -> OAuth Apps
2. Create a new OAuth application and name it Konnect Orchestrator
3. Set the Homepage URL to your platform team repository (or any other URL you choose)
4. Set the Authorization callback URL to the localhost URL of the self service application: http://localhost:8080/auth/github/callback
5. Register the new application and securely save the Client ID
6. Click the Generate a new client secret button and securely save the Client Secret value

These instructions detail how to use koctl to run the self service UI locally using Docker.

Just like any web based app, running the self service UI locally on Docker will not allow you to share access to the application with your users. It may be preferable for you to run the self service UI in a more production-like environment allowing your users to access the app from their own machines. These instructions do not cover that use case at this time. The Dockerfiles and built images can be found in the GitHub repository https://github.com/Kong/konnect-orchestrator

1. Run the run command from your shell:

    koctl run
   

2. Use the Tab and Enter keys to navigate through the prompts and enter the necessary information.
3. Enter the Client ID and Client Secret values you created in the previous step
4. Enter the URL of the platform repository you created in the previous steps
5. Enter the GitHub token secret you created for the platform repository in previous steps
6. The command will run two Docker containers which host the platform repository API server and a web UI that allows users to sign in with their GitHub accounts and select their service repositories

1. Open the self-service UI at http://localhost:8080 in your browser and sign in with your GitHub account
2. Select a GitHub Account or Organization you have access to and it will populate the list of repositories available and service repository to add to the platform
3. Select the repository you wish to add to the platform
4. Select the Production and Development branches in their respective drop down menus
5. Select or Add a team
6. Click the Add Service to Platform button and the orchestrator will file a PR to the platform repository
7. Once you have added the service, you will see the pending PR in the Pull Requests section of the self-service UI. The PR will have the following title: [Konnect Orchestrator] - Add Service <service-name>

In order for the reference platform logic to work, there must be an OpenAPI specification found in the service repository. The orchestrator will look for a file named openapi.yaml in the root of the repository. If necessary, the path can be overridden by changing the spec-path field in the teams.yaml configuration file staged by the PR.

1. The platform owner should then review and merge the PR. This will trigger the running of the koctl apply workflow which will 1) Apply the necessary configuration to the Konnect Organization and 2) copy the service API specification to the platform repository. The API specification will be staged as a PR in the platform repository.

Once the koctl apply workflow has successfully completed, the orchestrator will have created two PRs in the platform repository one for each environment (dev and prod). These PRs contain the addition of the service repository API specification to the platform repository and the addition of various patching files that are used to apply service specific configurations to the resulting decK configuration files.

Approving these initial PRs will initiate the APIOps workflows to deliver the APIs to Konnect. To see how the APIOps workflows operate, reference the APIOps page for the full details.

Once the APIOps workflows are complete, your platform is now setup! The APIOps workflows are in place, and the orchestrator has created resources for you within the Konnect Organization. Login to your Konnect account and review the resources created by the orchestrator.

• Explore the Kong Developer site fully to learn about the features and capabilities of Kong Gateway and Konnect.
• For unanswered questions on the reference platform, check out the FAQ page for additional information.
• If you have questions or feedback about the reference platform, please reach out on the Kong Community Forums.