DEV Community: Mateusz Szostok

Creating the Botkube Flux Plugin for Day 2 operations

Mateusz Szostok — Wed, 13 Sep 2023 10:07:30 +0000

Hey there, tech enthusiasts! Today we're diving into the world of GitOps with the brand-new Botkube Flux plugin.

Introduction

In Botkube, we move towards GitOps by developing extensions like the new Flux plug-in. We all know the importance of GitOps workflow automation—it's the backbone of modern Kubernetes management. But sometimes, we encounter situations where automation is needed but hasn't been implemented yet. That's where Botkube steps in.

The Botkube Flux plugin is designed to bridge the gap between your Kubernetes clusters and GitHub repositories. It enables you to execute commands directly from Slack using interactive forms. Plus, it keeps you in the loop by notifying you about GitHub pull requests that are altering your kustomization files. It provides a dedicated button to show a diff report between the pull request and your current cluster state.

In this blog post, we will reveal the cards and dive deep into the thought process and implementation details of the Flux plugin. You'll get to know the Zapier-like aspect of Botkube that connects Kubernetes clusters, GitHub, and the Flux CLI – all of this to make you fall in love with your Day 2 operations.

The Evolution of Flux Executor Plugin

Now, let's get into the nitty-gritty of this plugin's journey. Picture yourself as part of a team managing Kubernetes applications with multiple pull requests. Our goal is to integrate with Flux CD to simplify Day 2 operations for Flux users. Let's take a closer look at the user story:

Be able to run Flux CLI commands from any communication platform, just like you do in your terminal:
Next, let's make it mobile friendly. The secret ingredient is interactivity like buttons and select menus.

Typing or copy-pasting a long names doesn't work well. Now, you have a handy Flux client right in your pocket, ready with just a few clicks.
And we are just half-way there 😈
Here comes the last, but unique, part that makes the difference: support for Day 2 operations.
In our case, we stitched together three important parts: Kubernetes cluster, GitHub platform, and Flux CLI. As a result, we've provided a streamlined experience for generating a diff report in the context of GitHub pull requests and the current cluster state.

🎁 As you may notice, the diff report notification includes some useful actions out-of-the-box:
- Posting the diff report as a GitHub comment.
- Approving the pull request.
- Viewing the pull request.
Now, when we're happy about the result, we are still missing one more part to automate our day 2 operation.
Even though the diffing flow integrates with GitHub, it still requires two manual steps:
- discovering that a new pull request was created
- constructing a Flux related command

That's how the GitHub Events source was born. Now we can set up a complete workflow to:

Watch for GitHub pull requests that changes files in kustomize directory. Alternatively, we can use label selectors.
Get notification on Slack about new pull request.
Render and embed event-aware button to run a diff report.

Now, you may think that what we achieve in those 4 steps it's great but will be hard to configure. Is it? We hope that included YAML sample proves that it is not:

Flux Executor, with optional GitHub token:
GitHub Events workflow:

We've kept the syntax generic, allowing you to configure different command buttons under specific types of events.

Interactivity and Decision-Making

Thanks to automated notifications with event-aware buttons, you can easily generate reports and share them with your team or contributors.

While posting diff reports can be fully automated, you might want to do it intentionally by clicking a button. Why? Because the report may contain sensitive information that you don't want to fully disclose to external contributors.

Using, for example, GitHUb Action, unfortunately, doesn't give us this freedom. We tried to automate the whole workflow while still keeping you as the decision-maker when it comes to sharing the report or directly approving the PR.

With that being said, nothing blocks us from adding in the future support for AI assistance. Imagine an AI that reviews the diff report and decides whether to proceed with automated approval. Are you ready for AIOps? Exciting times ahead!

Manual Approach vs. Botkube Flux Plugin

While you were reading the first part of the Flux plugin evolution, did you consider what kind of manual steps would be required without the plugin? Let's break it down:

Checking GitHub repository for a new pull requests.
(One-time operation) Downloading and installing Flux CLI on you localhost.
Manually connecting to the related Kubernetes cluster.
(One-time operation) Cloning the repository.
Checking out the pull request.
Constructing a Flux command.
Sharing the diff report on Slack/GitHub.

Even if we exclude the one-time operations, we're left with 5 steps for each new pull request. Lots of manual steps mean lots of room for human errors. Plus, all that jumping between different sites and context switching can impact your productivity. It's much better to focus on the main aspect, which is the review, and let automation handle the rest.

Behind the Scenes: Developing the Botkube Flux Plugin

The development of the Botkube Flux Executor plugin involved several key aspects:

🕹️ Interactivity: We leveraged the exec plugin developed in previous release, making adding interactivity almost out-of-the-box. The exec plugin allows you to port any CLI into the communication platform window.
In this case, we reused it as Go SDK. Here is the blueprint that describes translation of CLI table output into an interactive message:

This makes the implementation much simpler, so we could focus more on native support for the diffing flow.
🗃️ Storing blueprints: The blueprints used for converting CLI output into interactive messages are not stored directly in the Go code. Instead, we store them as YAML files in a dedicated folder so that IDEs, the GitHub platform, and others can provide us with valid syntax highlighting and formatting.
Next, we use Go embed functionality, which is really handy here. With just three lines of code, Go embeds the entire directory with our manifests:

Thanks to embedding it, we can distribute it as a single plugin binary, and we don't need to make any external download calls on startup.
🔍 & 🔐 Auto-discovering GitHub repos: In order to discover related GitHub repository, we need to get Flux custom resource. We used the controller-runtime client, which supports Go types natively. This eliminated the need to work with the unstructured type, making things smoother and less error-prone. This is backed by dedicated plugin RBAC impersonation that we introduced a couple releases ago.
🔄 Cloning and checking out PR: Checking out a pull request can be tricky, especially when dealing with external contributors and their forks. Instead of reinventing the wheel, we integrated the widely-known gh CLI. It was easy to add an external dependency just by defining:

Under the hood we use go-getter library which has a lot of great features. If you need to download assets from different sources, we recommend that library your projects as well.

The trickiest part was to develop GitHub Events source. The best way is to use GitHub App with the webhook approach. However, we didn't want to require you to have an external endpoint exposed from your cluster.

We started with GitHub repository events endpoint. But it turned out that even though it serves events that we are interested in, it was not meant to be used for the real-time use-cases. We still integrate with the events API, but it's recommended for event subscription where time is not that important. For example, getting notification about new stars on your GitHub repositories:

To achieve our e2e goal, we decided to develop a custom polling mechanism that uses pull request endpoint. The polling mechanism forces us to be more rational about the number of calls to fit into defined rate limits. We decided on two things:

Conditional requests because receiving a 304 response doesn't count against token rate limit.
Adding support for GitHub App tokens. By using GitHub Apps, you can increase your maximum rate limits because multiple GitHub Apps are independent and do not share the rate limits. Where, using multiple Personal Access Tokens (PATs) for the same account will result in sharing the same rate limit.

In the future, we can consider adding a token rotator that automatically switches tokens before hitting the rate limit.

For the Botkube web app we will consider native integration using GitHub App, to reduce friction with the initial setup for Flux and GitHub Events plugins.

Conclusion

The Botkube Flux plug-in offers valuable solutions for streamlining GitOps workflows. Its capabilities, including mobile-friendly interactivity and automated Day 2 operations support, can significantly enhance your Kubernetes management.

We encourage you to explore the Botkube Flux plugin and consider integrating it into your workflows. Don't hesitate to share your feedback and ideas about Botkube. Feel free to reach out to us on Slack or Twitter.

Thank you for taking the time to learn about Botkube 🙌

Build a GitHub Issues Reporter for failing Kubernetes Apps with Botkube Plugins

Mateusz Szostok — Thu, 02 Feb 2023 09:38:50 +0000

Botkube gives you fast and simple access to your clusters right from your communication platform. It does that by sending actionable notifications (via sources) and allowing you to run kubectl and helm commands (via executors) straight from the platform (Slack, Discord, Microsoft Teams and Mattermost).

In the recent Botkube 0.17 release, we took it to the next level by giving you an easy way to bring your own tools to a chat window!

In this blog post, you will learn how to develop your own executor plugin to fill the gap in your daily workflow.

Goal

To make it simple but functional, I will show you how to develop an executor that creates an issue for failing Kubernetes resources such as Job, Deployment, StatefulSet, and Pod.

Why it's worth it

With just a few lines of code, we will automate the process of creating a GitHub issue that out-of-the box contains Kubernetes-specific information useful for further debugging. All of that, directly from Slack, Discord, Mattermost, or MS Teams! No need for connecting to your cluster in your terminal, installing and running kubectl commands and copy-pasting fetched details into your browser.

Instead, you will be able to type @Botkube gh create issue pod/foo from any device that has access to your chat, including mobile apps.

Prerequisites

Access to a Kubernetes cluster
💡 Tip
To create a local cluster for testing purposes using k3d, run:
```
k3d cluster create
```

Botkube installed and configured.
Basic understanding of the Go language
Go at least 1.18.

What's under the hood

To understand better what we will develop, I want to give you a bigger picture of the Botkube plugin system. The below animation focuses only on the executor part, but it's almost the same for sources.

The new part is a plugin repository that we introduced in 0.17. Plugin repository is a place where you store your plugin binaries and index files. Any static file server can be used, and in this blog post we will use a GitHub release. It’s similar to what you know from the Helm ecosystem.

The plugin manager consumes user's configuration, and downloads and starts only enabled plugins from a given repository. Plugins are running directly on the Kubernetes cluster where the Botkube core was installed.

Such approach allows us to decouple the Botkube core and its extensions. Thanks to that, we can:

Avoid having the Botkube core crash if a given plugin malfunctions
Write extensions in any language as gRPC is used

From the end-user's perspective, you can:

Specify and use multiple plugin repositories at the same time
Enable different plugin versions within the same Botkube version

To learn more, see Botkube architecture.

Step-By-Step Instructions

To quickly onboard you to Botkube plugins, we maintain the kubeshop/botkube-plugins-template repository that has all batteries included. Our first step is to bootstrap your own GitHub repository.

To check out the entire code, visit the Botkube GitHub repository.

Repository setup

Navigate to botkube-plugins-template.
Click Use this template, and then Create a new repository.

By doing so, you will create your own plugin repository with a single commit.

Clone your repository locally:

gh clone {owner}/{repo_name} # for example, gh clone mszostok/botkube-plugins

Create and push a new tag to perform the initial release:
```
git tag v0.0.1
git push --tags
```
After a few minutes you should see a new GitHub release.

Voilà! You are already an owner of fully functional Botkube plugins. Now it's time to add your own brick by creating a GitHub executor.

💡 Tip
In this blog post, we use only GitHub releases that work out-of-the-box. Releasing plugins on GitHub Pages requires additional setup. To support them too, see the use template document.

Develop GitHub executor

💡 Tip
To make the code-snippets more readable, I skipped the error handling. However, it will be useful if you will add error handling for the final implementation. You can check the full gh source-code for the reference.

Create a cmd/gh/main.go file with the following template:

This template code imports required packages and registers GHExecutor as the gRPC plugin. Our GHExecutor service already implements the required Protocol Buffers contract. As you can see, we require only 2 methods.
- The Metadata method returns basic information about your plugin. This data is used when the plugin index is generated in an automated way.
- The Execute method is the heart of your executor plugin. This method runs your business logic and returns the output as plaintext. Next, the Botkube core sends back the response to a given communication platform.
To download the imported dependencies, in your terminal, run:
```
go mod tidy
```
Great! At this stage you already have a functional Botkube executor plugin. However, for now, it only responds with a hard-coded "Aloha!" greeting. But it can do that already on all supported communication platforms.

Don't worry, in the next steps, we will implement our business logic.
Add support for user configuration:

For each Execute method call, Botkube attaches the list of associated configurations. The input parameters are defined by the user, when enabling a given plugin:
```
executors:
  "plugin-based":
    repo-name/gh:
      enabled: true # If not enabled, plugin is not downloaded and started.
      config: # Plugin's specific configuration.
        github:
          repository: "mszostok/repository"
          token: "github_pat_foo"
          issueTemplate: |
            ## Description

            This issue refers to the problems connected with {{ .Type | code "bash" }} in namespace {{ .Namespace | code "bash" }}

            {{ .Logs | code "bash"}}
```
In our case, we need to have a GitHub token, GitHub repository where the issue should be created, and an issue template. The remaining parameters can be hard-coded on the plugin side, however, your plugin will be more flexible if you allow your users to change it without rebuilding your plugins.

It's up to the plugin author to merge the passed configurations. You can use our helper function from the plugin extension package (pluginx). To learn more, see Passing configuration to your plugin.
Let's implement command parsing to properly understand command syntax:

Our goal is to parse gh create issue KIND/NAME [-n, --namespace].

There are a lot of great libraries supporting command parsing. The most popular is probably cobra, but for our use case, we will just use the helper function from our plugin extension package.

Under the hood, the pluginx.ParseCommand method uses go-arg.
We are almost there! Now let's fetch the issue details:

Here, we fetch logs and the cluster version, but you can extend it to fetch other details about your cluster. To make it as simple as possible, we use the kubectl CLI and avoid reimplementing a bit more complicated logic for fetching logs from all different Kubernetes kinds.
Render issue description:

In this step, we use the issue template that the user specified in plugin configuration. I decided to use the Go template, as it fits perfectly into our template rendering flow.
Finally! Submitting an issue!

GitHub provides a great gh CLI, which we use to submit our issue. To learn more about the CLI syntax, see their manual.

💡 Tip
The gh CLI doesn't accept fine-grained access tokens. As a workaround, you can use the Go SDK
The last part is to download our dependencies.

We already improved this step and in the 0.18 version Botkube will download defined dependencies automatically. For now, you can use the pluginx.DownloadDependencies function to call our downloader explicitly. The syntax will remain the same.

Congrats! The gh plugin is finally implemented. Now, let's play a DevOps role! 😈 In the next section, I will show you how to build and release your brand-new executor plugin.

Release the `gh` executor

It's time to build your plugin. For that purpose, we will use GoReleaser. It simplifies building Go binaries for different architectures. The important thing is to produce the binaries for the architecture of the host platform where Botkube is running. Adjust the goos, goarch, and goarm properties based on this architecture.

Add new build entry under .goreleaser.yaml:

builds:
  - id: gh
    main: cmd/gh/main.go
    binary: executor_gh_{{ .Os }}_{{ .Arch }}

    no_unique_dist_dir: true
    env:
      - CGO_ENABLED=0
    goos:
      - linux
      - darwin
    goarch:
      - amd64
      - arm64
    goarm:
      - 7

Now, we need to distribute our plugins. As we mentioned earlier, a plugin repository can be any static file server. The kubeshop/botkube-plugins-template repository comes with two GitHub Actions:

The .github/workflows/release.yml action, which builds the plugin binaries and index file each time a new tag is pushed.
The .github/workflows/pages-release.yml action, which updates GitHub Pages with plugin binaries and index file each time a new tag is pushed.

To cut a new release, you need to commit all your work and tag a new commit:

git add -A
git commit -m "Implement gh executor"
git tag v1.0.0

Next, let's push our changes and the new tag:

git push
git push --tags

This triggers GitHub Action:

What this automation does under the hood

This automation:

Installs the latest GoReleaser tool.
Builds all plugin binaries defined in the .goreleaser.yaml file.
Generates an index file using the Botkube helper tool.
Generates a release description.
Uses the gh CLI to create a new GitHub release.

Use the `gh` executor

In the description of a new GitHub release, you will see the repository URL that you can use within Botkube.

Steps

Follow one of our installation guides. Once you reach the Botkube deployment step, add flags specified in the steps below to helm install.
Export required environment variables:

💡 Tip
Follow the official GitHub guide on how to create a personal access token. To be able to create GitHub issues, add the repo permission.
```
export REPOSITORY={repo} # format OWNER/REPO_NAME, e.g. kubeshop/botkube
export GITHUB_TOKEN={token}
export PLUGINS_URL={plugin_index_url}
```

Add the gh executor related configuration:

--set 'plugins.repositories.botkube-plugins.url'=${PLUGINS_URL} \
--set 'executors.plugin-based.botkube-plugins/gh.config.github.repository'=${REPOSITORY} \
--set 'executors.plugin-based.botkube-plugins/gh.config.github.token'=${GITHUB_TOKEN} \

Depending on the selected platform, add the plugin-based executor binding. For Slack, it looks like this:
```
--set communications.default-group.socketSlack.channels.default.bindings.executors=['plugin-based']
```

If you follow all the steps above, you will have all the necessary flags allowing you to install Botkube with the gh executor!

Here's an example of a full command that you should have constructed for Slack installation:

Testing

Navigate to your communication channel
On a given channel, run:
```
@Botkube list executors
```
It should return information about enabled gh executor:
Create a failing Job:

After a few second, you should see a new alert on your channel:
To create a GitHub issue for a given alert, run:
```
@Botkube gh create issue job/oops
```

Summary

Botkube executors are powerful because they can glue together three important parts: Kubernetes clusters, communicators, and tools of your choice. There would be nothing special about it if it wasn't, in fact, unburdening you of those implementation-specific details.

As you noticed, you can focus purely on your business logic. Without the need to use different chat libraries, know how to establish secure connection, or make your extension available only on specific channels. What's more, not only do you not have to learn it, but you don't have to support it either, as we do it for you.

Once Botkube is deployed, your extension will be available to you and your teammates in a given channel. There is no need to maintain your local setup. Thanks to that, you can also easily run executors on private clusters.

Botkube extensions can be used with other Botkube functionality too. It means that you can use them to create automation. We will shed more light on that in the next blog post. Stay tuned!

Implement once, access everywhere (Slack, Discord, Mattermost, MS Teams).

How can I get involved?

The implemented plugin is as simple as possible. However, it is a great base for further extension based on your needs; for example: introduce your own Kubernetes annotation to route the notification to a specific repository, add a threshold to create issues only for constantly failing Pods, etc. The possibilities are endless, and we cannot wait to see what kind of great workflows you will create!

As always, we want to hear your feedback and ideas about Botkube. Help us plan the Botkube roadmap, get the features you’d like implemented.

There are plenty of options to contact us:

GitHub issues
Slack
or email our Product Leader at blair@kubeshop.io.

Thank you for taking the time to learn about Botkube 🙌

CLI version: a collection of handy tips

Mateusz Szostok — Tue, 27 Sep 2022 12:21:33 +0000

Edited by: Maja Szostok

Flag or Command?
- Flags
- Command
- Decision
What to collect
Output options
Bells and whistles
- Upgrade notice
- Version skew warning
Summary
Bonus

Including version information in CLIs is as obvious as a shower after a 3-day music festival. But have you ever given it a second thought?

I researched 16 popular CLIs to find out how they approach this, and ultimately to come up with a solution that is both elegant and useful.

In this article, I present my findings and outline both the good and the bad of each approach.

source: version.szostok.io

Flag or Command?

Before we discuss what we should display, let's talk about how our user can get the CLI version.

Flags

Let's take a look at the most popular options:

Name	Description
`-v`	Might be confusing, as `-v` is often used to enable the verbose mode. If you decide to use `-v` anyway, consider `-d, --debug` for more verbose output.
`-V`	Being a capital letter, it's a better alternative for `-v` as it's visually distinct.
`--version`	Is a self-descriptive alternative, mentioned by CLI guidelines as a common approach found in CLIs.

However, flags come with one big problem. It's hard to combine them with additional functionality. The most popular ones are:

Printing a help message with more information about the version itself.
Printing only the version number.
Printing only the client version when your CLI works with a server, like kubectl does.

There are some options to deal with that, but they have their own flaws:

<cli> -V --short — it's hard to tell which flags work together

A combination of function and -version suffix. For example:

<cli> --short-version

Unfortunately, this doesn't scale well. See:

<cli> --short-client-version
<cli> --short-server-version
<cli> --json-version
<cli> --json-client-version
<cli> --json-server-version

Command

An alternative solution is to have a dedicated <cli> version command, which gives you an easy way to:

Print a help message with <cli> version -h.
Combine it with other functionality. For example, --short, --json, --client-only, etc.
Introduce related sub-commands. For example, <cli> version check-update to check if there is a new release.

It requires more typing than <cli> -v, but you can add aliases, such as <cli> ver or even <cli> v. However, this is not something I saw often 🤔.

Decision

I guess all of us want to have our cake and eat it too 😎. In this one case, it's possible. Personally, I would suggest having the --version flag to print the short version, and the <cli> version command to support more complex use cases.

What to collect

Version information is your CLI's DNA. The data that you collect and display is later useful for the CLI authors and its users. Users want to easily check if they're using the right version. Authors mostly want to find out what revision of the source code was used for a given CLI version, e.g. in case of a bug report.

Users are the most important part of our projects. Let's start with their needs first!

Get the CLI version — the best option is to use semantic versioning here.
- Get both the client and the server version, if available.
Note: Make sure that you have an option to print the client version only.
Be informed about using an outdated version or version skew.
Get the URL to the GitHub release and/or documentation.

For you as the author, displaying these details can come in handy:

Git commit — the SHA for the commit that a given version was built from.
Git state — for example, clean if there are no local code changes when this binary was built; dirty if the binary was built from locally modified code.
Build date — the date when the binary was built.
Programming language version — the version of the language that was used to compile your binary.
Build user — the creator of the binary. It can be also the name of your automation, e.g. goreleaser-1.11.2.
Related components' versions — the versions of the binaries that are used under the hood, e.g. Git, Docker. A good example, of collecting such information is Minikube (example).

Output options

The final aspect is how to present the data to the user. The most popular option is to print a human-readable message if no flags are specified.
However, for doing version check, options such as short, YAML, and JSON are useful.

Name	Description
--output= json \| yaml \| short	Displays the version information in the JSON format.
--client-only	Displays only the client version.

As a result, on a CI pipeline, we can easily detect a mismatched version:

EXPECTED_VERSION="1.42.0"
GOT_VER=$(golangci-lint version --format=short 2>&1)

if [[ "${GOT_VER}" != "${GOLANGCI_LINT_VERSION}" ]]; then
  echo "✗ golangci-lint version mismatch, expected ${EXPECTED_VERSION}, available ${GOT_VER}"
  exit 1
fi

An unusual finding for me was that Helm CLI supports Go templates. For example, --template='Version: {{.Version}}' outputs 'Version: v3.2.1'. I personally don't see how it adds value if you already support the JSON and/or YAML output format. Do you find it useful?

Bells and whistles

The below practices stood out as a nice touch for me as a user.

Upgrade notice

Inform your user when a newer version was released. Additionally, you can detect what option was used for installing your CLI, e.g. brew, apt, etc., and suggest a command ready to copy-paste.

Let me show you a few examples:

GitHub CLI. The upgrade notice is enabled by default. To disable it, you need to export the GH_NO_UPDATE_NOTIFIER environment variable. It checks for new releases once every 24 hours, and displays an upgrade notice on stderr error if a newer version was found. Here is an example output:
```
A new release of gh is available: 2.5.1 → v2.5.2
To upgrade, run: brew update && brew upgrade gh
https://github.com/cli/cli/releases/tag/v2.5.2
```
OpenFaaS CLI. The upgrade notice is enabled by default. To disable it, you need to specify the --warn-update=false flag. Here is an example output:
```
Your faas-cli version (0.14.5) may be out of date. Version: 0.14.6 is now available on GitHub.
```

Terraform CLI. The upgrade notice is always enabled, however, when the JSON format is used, it only shows the terraform_outdated property set to true.

Terraform v1.2.8
on darwin_amd64

Your version of Terraform is out of date! The latest version
is 1.2.9. You can update by downloading from https://www.terraform.io/downloads.html

Version skew warning

Print a warning message if the difference between the CLI and related components is greater than the supported version skew.

The related components include but are not limited to the server that your CLI connects to, and/or other binaries that are used under the hood, such as Git, Docker, etc.

Summary

You may think: printing CLI version… isn't that obvious? Don't you have better things to do instead of thinking how to implement it? And yet, we can find a lot of different approaches. It bothered me sooooo much that I decided to do this research and structure my knowledge in this area. I hope, that you found it useful, too. Thanks for reading!

Follow @m_szostok on Twitter to get the latest news.

Bonus

If you use Go to create your CLI, you don't need to reinvent the wheel - I got your back! You can use the version package, which was made to remove repetitiveness in implementing the version command.

The details about the CLIs that I analyzed can be found at mszostok/cli-analysis.

Take Capact for a spin!

Mateusz Szostok — Mon, 07 Feb 2022 13:59:23 +0000

Our first blog post focused strongly on why—why we created Capact, what's the general concept behind it. Now it's time for showing how—how you can use it.

Although, there are many ways to get started with Capact, today we will focus on your perspective as a Capact User.

The recommended way to try out Capact quickly is to set up a local environment.

Detailed instructions are already nicely described in our local installation tutorial. Once you have Capact up and running, we can start!

What you will learn

NOTE: For this blog post, we will use Capact CLI. However, the described scenario can also be executed with our brand-new UI! 😎

In 5 minutes, by running examples from this blog post, you will learn about the following Capact concepts:

Interface—provides an option to abstract Implementations.
Implementation—defines the actual workflow that is executed.
Attribute—provides an option to tag manifests. Today we will use it to select a specific Implementation.
Type and TypeInstance—provide a combined feature, where Type holds the schema and TypeInstance the instance for the Type.
Action—triggers Engine to render and run a given Interface.
Policy—impacts the render process to select desired Implementations.

Creating new workflows is not the concern of this article, and it will be covered in future blog posts.

Here we only briefly describe each part, but I encourage you to take a deeper look at our Terminology section later.

Prerequisites

Capact CLI at least v0.6.0
Capact cluster at least v0.6.0
(Optional) kubectl
jq

📜 Scenario

The key concepts were described in the Introducing Capact blog post. There, we used Mattermost as an example. It was a real life scenario but at the same time more resource and time-consuming.

For the purpose of this blog post, we created an extremely simple Hello World example.

There are two Implementations for the cap.interface.capactio.examples.say Interface. Depending on the Policy, a different Implementation is selected. By default, Engine selects the Implementation which is first on the list (alphabetical order) and doesn't have any requirements regarding executions, such as requiring AWS credentials.

🎬 Camera, Lights, Action!

Action is the entry point for executing any Interface. It allows you to define which Interface should be executed and with which parameters. This is later consumed by Capact Engine and the appropriate workflow is rendered. Later, you can review it and approve it for the execution.

Steps

Make sure that you are logged into local cluster.

List available Interfaces:

capact hub interfaces get

We are interested in this part:

                           PATH          LATEST REVISION                  IMPLEMENTATIONS
---------------------------------------+-----------------+-----------------------------------------------
# ... trimmed ...
---------------------------------------+-----------------+-----------------------------------------------
cap.interface.capactio.examples.greet        0.1.0             cap.implementation.capactio.examples.greet
---------------------------------------+-----------------+-----------------------------------------------
cap.interface.capactio.examples.say          0.1.0             cap.implementation.capactio.examples.hello
                                                               cap.implementation.capactio.examples.ricky

Create a new Action:

💡 A Policy is not needed as we use the default behavior here.
```
capact act create --name hello cap.interface.capactio.examples.greet
```
Wait for the Action to have the READY_TO_RUN status:
```
 capact act get hello
```
When the status is READY_TO_RUN, run the Action:
```
 capact act run hello
```
Watch the progress:
```
 capact act watch hello
```

(Optional) Once the Action is finished, copy the name of the Pod for the print workflow step (column PODNAME). To read its logs, run:

kubectl logs {PODNAME} main

Example output:

 ____________________________
< message: Hello from Capact >
 ----------------------------
    \
     \
      \
                    ##        .
              ## ## ##       ==
           ## ## ## ##      ===
       /""""""""""""""""___/ ===
  ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
       \______ o          __/
        \    \        __/
          \____\______/

Get the Action output (TypeInstance). Copy the id field value:

 capact act get hello -ojson | jq '.Actions[0].output.typeInstances'

Example output:

[
 {
   "id": "08fcaa07-7846-47af-b6a7-7c3818c69656",
   "typeRef": {
     "path": "cap.type.capactio.examples.message",
     "revision": "0.1.0"
   }
 }
]

Get the TypeInstance value.message field value:

 capact ti get {ID} -ojson | jq -r '.[0].latestResourceVersion.spec.value.message'

Delete the Action:
```
 capact act delete hello
```

What if you wanted to output a different message, that reminds you about a masterpiece song you can listen to endlessly? With Capact that's really easy ✨

To choose a different Implementation for the say Interface, we need to prepare a dedicated Policy. The power of it is that you don't have to change the main workflow. You treat the step as a building block and just swap it for another existing one.

To test it, create the Action again, and pass the Action Policy.

First, save the Policy to the /tmp/policy.yaml file:

cat <<EOF > /tmp/policy.yaml
rules:
  - interface:
      path: cap.interface.capactio.examples.say
    oneOf:
    - implementationConstraints:
        attributes:
          - path: cap.attribute.capactio.examples.be-positive
            revision: 0.1.0
EOF

Next, create the Action with the Policy:

capact act create --name hello cap.interface.capactio.examples.greet --action-policy-from-file /tmp/policy.yaml

Now, you can repeat steps starting from 4th point—so, once again, wait for the Action to have the READY_TO_RUN status and run it!

In the optional step no. 7, if you read the Pod logs, the output will be:

 __________________________________
< message: Never gonna give you up >
 ----------------------------------
    \
     \
      \
                    ##        .
              ## ## ##       ==
           ## ## ## ##      ===
       /""""""""""""""""___/ ===
  ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ /  ===- ~~~
       \______ o          __/
        \    \        __/
          \____\______/

Note also that the produced TypeInstance from no. 9 is valid against the same JSON Schema but the message was changed.

What is so special about it?

Our example was simplified to a minimum, but you could see that you can:

chain different steps together,
have a unified way of execution,
built-in Type validation based on JSON Schema,
and more importantly, write once and swap implementation details with ease.

Capact is also great if you want to chain different tools together and keep the same entry point (UX) but that requires more complex examples. For now, we recommend you to take a look at our other examples described in the How can I get involved and learn more? section.

Behind the CLI

As you saw, you can use CLI to browse Hub manifests, create a specific Action for a given Interface and retrieve the output. CLI communicates with our Gateway via GraphQL calls, same as the UI (Capact Dashboard). You can read more in the E2E Architecture document.

However, a more important question is, how did it happen?

1  spec:
2    # ... trimmed ...
3    imports:
4      - interfaceGroupPath: cap.interface.capactio.examples
5        alias: examples
6        methods:
7          - name: say
8  
9    # ... trimmed ...
10   steps:
11     - - name: get-message
12         capact-action: examples.say # dynamic step, rendered by Engine based on the Policy.
13     - - name: print
14         template: print
15         arguments:
16           artifacts:
17             - name: message
18             from: "{{steps.get-message.outputs.artifacts.message}}"
19     # ... trimmed ...
20     - name: print
21       inputs:
22         artifacts:
23           - name: message
24           path: /tmp/message.yaml
25       container:
26         image: docker/whalesay:latest
27         command: [ sh, -c ]
28         args: [ "cowsay < /tmp/message.yaml" ]

The snippet above shows the most important parts of the Implementation manifest. In lines 4-7, we declare the import, which is later used in steps. In line 12, we use capact-action to make a dynamic step with a given Interface.

💡 Instead of providing the full Interface path, we use alias assigned to the imported Interface.

As a result, our Engine and, in particular, Argo Renderer has an option to put there an Implementation that fulfills the specified Interface. Thanks to that, this step is swappable based on the defined Policy.

How can I get involved and learn more?

The Getting Started goes into more detail about how to start with Capact and use its more-advanced features. There are also Rocket.Chat and Mattermost tutorials that we keep up-to-date for you to walk you through using Capact in real cases.

We appreciate any input you have about your experience with Capact!

There are plenty of options to contact us:

Thank you for taking the time to learn about Capact 🙌

DEV Community: Mateusz Szostok

Creating the Botkube Flux Plugin for Day 2 operations

Introduction

The Evolution of Flux Executor Plugin

Interactivity and Decision-Making

Manual Approach vs. Botkube Flux Plugin

Behind the Scenes: Developing the Botkube Flux Plugin

Conclusion

Build a GitHub Issues Reporter for failing Kubernetes Apps with Botkube Plugins

Goal

Why it's worth it

Prerequisites

What's under the hood

Step-By-Step Instructions

Repository setup

Develop GitHub executor

Release the gh executor

Use the gh executor

Steps

Testing

Summary

How can I get involved?

CLI version: a collection of handy tips

Table Of Contents

Flag or Command?

Flags

Command

Decision

What to collect

Output options

Bells and whistles

Upgrade notice

Version skew warning

Summary

Bonus

Take Capact for a spin!

What you will learn

Prerequisites

📜 Scenario

🎬 Camera, Lights, Action!

Steps

What is so special about it?

Behind the CLI

How can I get involved and learn more?

Release the `gh` executor

Use the `gh` executor