Skip to main content
Version: 1.12

Botkube app for Microsoft Teams

This document describes the communication between the Botkube Cloud control-plane and the Botkube Agent configured with the Cloud Teams platform enabled.

teams-cloud.svg

Agent outbound connections​

  • HTTPS: https://api.segment.io/*
  • HTTPS: https://api.botkube.io/*
  • HTTPS: https://github.com/kubeshop/botkube/releases/download/*
  • HTTP/2: teams.botkube.io:50054
  • Docker images: https://ghcr.io more about required ports you can on About GitHub's IP addresses:
    • *.github.com
    • *.pkg.github.com
    • *.ghcr.io
    • *.githubusercontent.com

Agent inbound​

The Botkube Agent doesn't export any endpoints.

Components details

Agent​

The Botkube Agent Docker image is hosted on the GitHub Container registry, which uses the package namespace https://ghcr.io. The image format link:

Plugin manager​

The index and archives for open source plugins are stored under a given Botkube GitHub release as its assets:

For the Botkube Cloud exclusive plugins, we serve plugin index via the Botkube Cloud API (api.botkube.io). As we use Google Cloud Storage as the storage provider, all the plugins are fetched from the https://storage.googleapis.com origin.

During startup, the Botkube Agent downloads plugins index and all enabled plugins. They are stored under the /tmp folder mounted as the emptyDir. There is no Persistent Volume (PV), meaning that when the Agent Pod is, for example, rescheduled to another node, it downloads all dependencies again. To ensure that the plugin manager does not make external calls, all required plugins must be present. You can achieve this by mounting a Persistent Volume Claim (PVC) at this path. Later, you can mount your Persistent Volume (PV) with cached plugins.

Plugin dependencies​

Each plugin may define required external dependencies that are downloaded by the Plugin manager at Agent startup. For now, those dependencies are taken from the official sources and are not mirrored to the Botkube Cloud registry. Here are the links that describe external dependencies for each officially supported plugin:

helm plugin:

If a plugin is not listed here, then it doesn't have any external dependencies.

Analytics​

The Agent uses the official Go SDK to send anonymous analytics to https://segment.io. This library is sending a POST request on the https://api.segment.io endpoint.

Control-plane connection​

The Agent communicates with the Cloud control-plane using GraphQL. All requests are executed as a POST request on the https://api.botkube.io/graphql endpoint. We use that connection to:

  • Fetch Agent's configuration
  • Send audit logs
  • Periodically send Agent heartbeat
  • Watch configuration changes
    • all changes e.g., changing plugin configuration done on the Cloud UI Dashboard triggers Agent restart with 1 min (polling is used)

Security​

The https://api.botkube.io/graphql endpoint is protected by JWT tokens. For the Agent, we use machine API tokens that are issued separately for each Botkube Instance. This token allows you to work only in the context of a given Instance.

Cloud Teams connection​

The Cloud Teams platform communicates only with the Botkube control-plane using gRPC (HTTP/2 connection). For gRPC, TLS is enabled. We use bidirectional streaming RPC to send the user @Botkube commands to the Agent and send Agent responses back to the Cloud control-plane.

Security​

The teams.botkube.io:50054 connection is protected by machine API tokens that are issued separately for each Botkube Instance. This token allows you to work only in the context of a given Instance.

Concurrency Limits​

Concurrency limits restrict the number of simultaneous connections to our Cloud Teams router. You are allowed a maximum of 2 concurrent connections to support rollback updates.

Rate Limiting​

Rate limiting controls the frequency of requests that a component can send or receive. Rate limiting protects the Cloud Teams Router from misconfigured installations that may overload the system. Rate limiting is based on the Agent’s Instance ID. We drop any messages that exceed the limit and do not push them into Pub/Sub. You are allowed a maximum of 20 requests per second.

Cloud Dashboard​

Such constrains applies in the context of the Cloud organization:

  1. The organization has exactly one owner
  2. The organization owner cannot be removed.
  3. The organization owner is also a billing person.
  4. All organization members have the same full permission. They can add and remove members and update organization information.
  5. A user can be a member of multiple organizations.
  6. Instances are always scoped to a given organization.

Terminology​

Botkube Instance​

A Botkube Instance is created on the Botkube Cloud side and holds the Botkube Agent configuration.