Kubernetes Monitor Message Contracts

This repository contains the Protobuf contracts and the generated gRPC SDKs that are used for communication between Octopus Server and the Octopus Kubernetes Monitor.

Guidelines

General

• This repository is set up with release please to handle versioning, changelogs and releasing. To ensure that the changelogs are generated correctly, please use conventional commits when merging a PR into main.

Protos

• All Protobuf definitions should be placed in the protos directory.
• Updates to existing definitions should be backward compatible.
• Follow the 1-1-1 rule: All proto definitions should have one top-level element and build target per file. A canonical example of this would be the fetch_container_logs contracts.
  • fetch_container_logs_request.proto
  • fetch_container_logs_response.proto
  • fetch_container_logs_service.proto
• Language specific proto properties shouldn't be added directly in the Proto file but rather in the buf.gen.yaml configuration under the key managed.override

Prerequisites

• Buf CLI
• .NET 8.0
• Go 1.24

Optionally

• Buf account - To avoid rate limiting issues when generating SDKs

How To

Add a new Protobuf contract

1. Create new *.proto file(s) within the protos directory - Depending on what you are adding you might need multiple proto files to follow the 1-1-1 rule
2. Run buf format -w in the root directory of the repository to automatically format the proto files
3. Run buf lint to ensure that the proto files meet the linting requirements. (If you don't run this locally it will run as a PR required check)
4. Run buf generate to generate the SDKs

Update an existing Protobuf contract

1. Make changes to your desired Proto file, ensure the changes are backward compatible see: Protobuf best practices
2. Run buf format -w in the root directory of the repository to automatically format the proto files
3. Run buf lint to ensure that the proto files meet the linting requirements. (If you don't run this locally it will run as a PR required check)
4. Run buf breaking --against .git#subdir=protos to detect any breaking changes(If you don't run this locally it will run as a PR required check)
5. Run buf generate to generate the SDKs

Releasing new version

When a change has been merged into main, the release Github action will kick off and create a release please PR with the title chore: release main, after approving and merging this PR a Github release and tag will be created automatically and cause the build Github action to kick off to pack and push the generated SDKs to their associated package repositories.

Testing changes locally

Dotnet SDK

To use a local version of the Dotnet SDK you can use a local NuGet package source and add your locally built NuGet package there, then you will be able to install the local NuGet package in your Dotnet project.

# Add a local NuGet package source
dotnet nuget add source -n Local ~/dev/LocalPackages/

# Pack SDK into NuGet package 
dotnet pack lib/csharp/Octopus/Octopus.Kubernetes.Monitor.MessageContracts -o {PATH_TO_LOCAL_NUGET_PACKAGES}

# Example
dotnet pack lib/csharp/Octopus/Octopus.Kubernetes.Monitor.MessageContracts -o ../LocalPackages/

Go SDK

You can use a local version of the Go SDK by using a replace directive in the Kubernete's monitor Go module file.

replace github.com/octopusdeploy/kubernetes-monitor-contracts => {PATH_TO_LOCAL_REPO}

// Example
replace github.com/octopusdeploy/kubernetes-monitor-contracts => ../kubernetes-monitor-contracts/lib/go

Configuration

Versioning

Each generated SDK is versioned and released at the same time however the version number differ slightly depending on the language's version number requirements e.g. For version 0.1.2 of the contracts would result in two Github releases/tags

• Dotnet: csharp-sdk: v0.1.2
• Go: v0.1.2

For branch builds of the SDKs(Currently only the dotnet SDK is affected by this) the version number will be generated based on this following pattern

{CURRENT_VERSION}-{BRANCH_NAME}-{SHORT_COMMIT_SHA}

// Example 
0.1.2-exciting-new-feature-e1f2999

Linting

Buf is configured to use the BASIC linting rules with some exceptions which can be seen in the buf.yaml file.