Forem: Rocket.Chat

Beginners' guide to Go Contexts: The Magic Controller of Goroutines

Debdut Chakraborty — Fri, 06 Mar 2026 21:17:15 +0000

We've all used contexts, usually by passing them to functions that require them, like HTTP handlers or database queries. But what exactly are contexts, and how do they work under the hood?

In Go, a Context is essentially a signal. It travels through your functions to tell them when they should stop working because the data is no longer needed.

The Basic Check

The most fundamental way to use a context is to check its state manually. This is perfect for long-running loops or heavy calculations. If a function is a "one-off" and finishes instantly, a context doesn't add much value.

However, for a loop like this:

func process(ctx context.Context) {  
    for i := range 1000000 {  
        // check if the signal says we should stop  
        if err := ctx.Err(); err != nil {  
            fmt.Println("stopping early:", err)  
            return  
        }  

        // simulate some work  
        _ = i   
    }  
}

If we didn't have that if err := ctx.Err() check, the goroutine would keep spinning even if the user who started it has already disconnected or timed out.

Powering up with Select

While checking ctx.Err() works for loops, the real magic happens with the select statement. This is how you make a goroutine "listen" for a cancellation signal while it is busy doing something else, like waiting for a channel.

Waiting for a result

Imagine you are fetching data from a slow API. You want the data, but you aren't willing to wait forever.

func fetch(ctx context.Context) {  
    resultCh := make(chan string)

    go func() {  
        time.Sleep(5 * time.Second) // simulate a slow task  
        resultCh <- "got the data!"  
    }()

    select {  
    case res := <-resultCh:  
        fmt.Println("received:", res)  
    case <-ctx.Done():  
        // ctx.Done() is a channel that closes when the context is cancelled  
        fmt.Println("gave up waiting:", ctx.Err())  
    }  
}

By using select, your code becomes responsive. The moment the context expires, the <-ctx.Done() case triggers, and your function can exit immediately instead of hanging for the full 5 seconds.

Layered Control

Contexts are designed to be passed down. If you create a "child" context from a "parent," and the parent is cancelled, all the children are cancelled too. This lets you stop an entire tree of goroutines from one single place.

func run(ctx context.Context) {  
    // create a child context we can cancel manually  
    ctx, cancel := context.WithCancel(ctx)

    go process(ctx) // this starts the loop from earlier

    // simulate another part of the app failing  
    go func() {  
        time.Sleep(2 * time.Second)  
        fmt.Println("something else failed!")  
        cancel() // this kills the 'process' goroutine too  
    }()  
}

Making Existing Code Context-Aware

You might have a library or an old function that doesn't support contexts yet. How do you "wrap" it so it respects a timeout?

The trick is to run the old code in a separate goroutine and use a select statement to wait for either the result or the context signal.

func ContextAwareWrapper(ctx context.Context, data string) (string, error) {  
    resultCh := make(chan string, 1)

    go func() {  
        // call the old, non-context-aware function  
        resultCh <- OldLegacyFunction(data)  
    }()

    select {  
    case <-ctx.Done():  
        // if the context expires first, we return an error  
        return "", ctx.Err()  
    case res := <-resultCh:  
        // if the work finishes first, we return the result  
        return res, nil  
    }  
}

Note: Using a buffered channel (make(chan string, 1)) is important here. It ensures that if the context times out and we exit the function, the goroutine still running the OldLegacyFunction can send its result to the channel and exit without getting stuck forever (a goroutine leak).

The Importance of Cancel and Defer

Whenever you use context.WithCancel, WithTimeout, or WithDeadline, the standard library gives you back a new context and a cancel function.

You must call that cancel function.

Even if your function finishes successfully, you should call it. The best way to do this is with defer.

func main() {  
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)  
    // this ensures that when main finishes, the context is cleaned up  
    defer cancel() 

    doWork(ctx)  
}

Why is this important?

Resource Cleanup: Behind the scenes, the parent context keeps track of its children. If you don't call cancel, the parent might keep a reference to the child in memory until the parent itself dies, leading to a memory leak.
Stop Ongoing Work: Calling cancel() sends the signal through the ctx.Done() channel. It tells every function using that context: "The party is over, stop whatever you are doing."

Conditions, Phases, and Declarative Phase Rules in Kubernetes Operators

Debdut Chakraborty — Fri, 13 Feb 2026 22:40:31 +0000

Tl;Dr;

You can start with experimenting with the demo: https://debdutdeb.github.io/kubernetes-phase-rules/, linking conditions with phases. It's fun. At least was to me.
Spec = desired state; status = observed state. Controllers write status; the API conventions describe this split and the role of conditions.
Conditions are the right primitive: one observation per condition type, standardized and tooling-friendly. We use specific condition types so each observable fact is explicit and consumable.
Phase is still useful as a single, high-level label for observability (UIs, alerts, filters), but it should be derived from conditions, not maintained as a separate state machine.
Phase rules declare “when these conditions hold, phase is X.” The first matching rule wins. That keeps a single source of truth (conditions), makes phase logic testable and explicit, and avoids duplication across consumers.
The kubernetes-phase-rules (https://github.com/debdutdeb/kubernetes-phase-rules) package provides the rule types, matchers, and a StatusManager that keeps conditions and phase in sync and patches status for you.

The problem we faced

At Rocket.Chat we have an operator called Airlock that originally started as an operator for mongodb user management. But recently expanding to help us manage a few more aspects of our database operations.

We added a custom resource, Backup, whose status depended on several independent facts: Is the backup store available? Is database access granted? Has the backup job been scheduled? Did it complete or fail? Each of those is a separate observation, and in practice they’re often discovered or updated at different times, sometimes by different parts of the same controller or even by different controllers. So we ended up with multiple conditions on one resource: BucketStoreReady, MongoDBAccessRequestReady, JobScheduled, JobCompleted, JobFailed, and so on.

We also needed one phase—a single label like Pending, Running, Completed, or Failed—for UIs, alerts, and runbooks. That phase had to reflect the combination of all those conditions: “Failed if the store is missing or the job failed; Running if the store and access are ready and the job is scheduled; Completed if the job completed,” etc. The hard part was managing that mapping as we scaled out: multiple controllers or reconciliation steps each setting a subset of conditions, and every consumer (and the controller itself) needing a consistent answer to “what phase is this?” without reimplementing the same condition→phase logic in multiple places. We wanted a single source of truth (the conditions), one place that defined how conditions map to phase, and no drift between what the controller thinks the phase is and what dashboards or alerts assume.

This is about why conditions are the right primitive, why we still want a phase, and how phase rules let us derive phase from conditions in one place and keep everything in sync, including when multiple controllers touch the same resource.

The post will consistently refer to airlock and the backup resource as examples. It's easier that way for my memory to keep track of things.

Spec and status: desired vs observed

In the Kubernetes API, every resource that has mutable state is split into two parts:

spec — The desired state: what the user or automation asked for. It is the source of truth for “what should be true.”
status — The observed state: what the system has actually observed. Controllers write here; users typically don’t. It answers “what is true right now.”

The Kubernetes API conventions spell this out clearly: the specification is a complete description of the desired state and is persisted with the object; the status summarizes the current state and is “usually persisted with the object by automated processes.” So when you build a controller, you read spec, do work, and write what you observed into status.

That separation matters. It keeps user intent (spec) from being overwritten by controller updates, allows different access control for spec vs status, and gives clients a stable place to read “what’s actually happening” without parsing controller logic.

Why conditions (and why specific ones)

The standard way to put “what’s actually happening” into status is conditions. A condition is a single observation: a type (e.g. Ready, JobCompleted, BucketStoreReady), a status (True, False, or Unknown), and usually a reason and message. The API conventions describe conditions as “a standard mechanism for higher-level status reporting”: they let tools and other controllers understand resource state without implementing your controller’s logic. Conditions should “complement more detailed information” in status; they’re the contract for “is this thing ready / failed / still working?”

So why specific condition types? Because each condition should represent one observable fact. If you only had a single “Status” condition, you’d lose information: you couldn’t tell “store not ready” from “job failed” from “job still running.” By defining conditions like:

BucketStoreReady — Can we see and use the backup store?
MongoDBAccessRequestReady — Is database access granted?
JobScheduled — Has the backup job been scheduled?
JobCompleted — Did the job finish successfully?
JobFailed — Did the job fail?

you give the controller a place to report each fact as it learns it, and you give dashboards, alerts, and other controllers a way to react to specific causes (e.g. “alert when JobFailed is True” or “show message when BucketStoreReady is False”).

The conventions also say: condition type names should describe the current observed state (adjectives or past-tense verbs like “Ready”, “Succeeded”, “Failed”), and the absence of a condition should be treated like Unknown. So you design conditions to be small, explicit observations; the controller sets them as it reconciles; and the rest of the system consumes them without reimplementing your state machine.

Why phase when we already have conditions?

Conditions are the right primitive: they’re granular, extensible, and standardized. But they’re also many. For a Backup or any other resource for that matter, you might have five or six conditions. For a user or a dashboard, the first question is often: “What state is this in? Running? Failed? Pending?” Answering that from raw conditions means “run the same logic the controller would use to decide the high-level state” — and that logic then lives in every consumer (CLI, UI, Prometheus, runbooks). That duplicates logic and drifts over time.

A familiar example is the Node in Kubernetes. The node controller and kubelet set several conditions on a Node (e.g. Ready, DiskPressure, MemoryPressure, NetworkUnavailable). Those conditions drive behavior: the scheduler uses them to decide where to place pods; taints and other node properties can be updated based on conditions. But for “is this node usable?” you need a single picture. The Node’s phase (e.g. Running) is that summary, the final, high-level state that users and automation care about. So conditions are the levers the system uses to change node properties and make decisions; phase is the outcome you read when you want to know the node’s overall state.

So we still want a phase: a single, high-level label like Pending, Running, Completed, or Failed that means “the outcome of applying our rules to the current conditions.” Phase is the observability contract: one field that UIs can show in a column, that alerting can filter on (“alert if phase != Ready”), and that runbooks can branch on, without each consumer reimplementing the condition→state rules.

The Kubernetes API conventions actually deprecate the old use of phase as a first-class state-machine enum in core resources, because adding new enum values breaks compatibility and phase was often used instead of explicit conditions. The better pattern is: conditions are the source of truth; phase is a derived summary. So we keep conditions as the only thing the controller writes, and we compute phase from those conditions using a clear, declarative set of rules. That way we get the observability benefit of a single phase field without turning phase into an independent state machine.

The phase rule idea

Instead of the controller imperatively setting phase in code (“if store missing then phase = Failed”), we declare rules: “phase is Failed when condition A is True or B is True; phase is Running when C and D are True and E is False; …”. The relationship is one-way:

The controller only updates conditions (e.g. via SetCondition).
Phase is derived by evaluating an ordered list of phase rules over the current conditions.
The first rule whose condition matcher matches the current conditions gives the phase; if none match, phase is Unknown.

So conditions drive phase, phase never drives conditions. The same condition set always produces the same phase for a given rule list. Rule order encodes priority (e.g. “Completed” before “Running” before “Failed” before “Pending”). Because phase is always recomputed from the current conditions, it doesn’t matter which controller or which reconciliation step last wrote a condition—whoever updates conditions, the same rules apply and phase stays consistent.

Example (conceptually): For a Backup custom resource:

Phase Completed when: BucketStoreReady=True, MongoDBAccessRequestReady=True, JobCompleted=True.
Phase Running when: store and access are True, JobScheduled=True.
Phase Failed when: store or access is False, or JobFailed=True.
Phase Pending when: store or access is Unknown, or job not yet scheduled.

Each of these is a phase rule: a phase name plus a matcher over conditions. You evaluate the list in order; the first match wins. That’s the phase rule idea: declarative, testable, and a single place to define “what phase means.”

The kubernetes-phase-rules package

The kubernetes-phase-rules module provides exactly that: a small, experimental and potentially incomplete Go library for defining phase rules and computing phase from []metav1.Condition.

The core type is the PhaseRule interface. A phase rule has three methods: Satisfies(conditions) returns true if the given slice of metav1.Condition matches the rule (e.g. all required conditions present with the right statuses for an AND rule, or at least one for an OR rule); Phase() returns the phase name this rule represents (e.g. "Running", "Failed"); ComputePhase(conditions) returns that phase name when the rule is satisfied, and the constant PhaseUnknown ("Unknown") otherwise. So a phase rule is “when these conditions hold, the phase is X”; you build concrete rules with NewPhaseRule(phaseName, matcher) and pass them to the StatusManager or evaluate them yourself.

type PhaseRule interface {
    Satisfies(conditions []metav1.Condition) bool
    Phase() string
    ComputePhase(conditions []metav1.Condition) string
}

Package rules — You build phase rules with NewPhaseRule(phaseName, matcher). Matchers are built from:
- ConditionEquals(conditionType, statuses...) — this condition type must have one of the given statuses (True, False, Unknown).
- ConditionsAll(...) — all of the given condition matchers must match (logical AND).
- ConditionsAny(...) — at least one must match (logical OR).

Given a slice of metav1.Condition, you call rule.Satisfies(conditions) or rule.ComputePhase(conditions); for a list of rules, you iterate in order and take the first satisfied rule’s phase (or PhaseUnknown).

Package conditions — A StatusManager ties this into controller-runtime: you give it the CR’s status conditions pointer, the CR (implementing a small interface with SetPhase / GetPhase / SetObservedGeneration), and the phase rules. When you call SetCondition or SetConditions, it updates the condition slice, recomputes phase from the rules, updates the object’s phase and observed generation, and patches status via client.Status().Patch only when something changed. So the controller only sets conditions; the manager keeps phase and status in sync.

// Yes, I ran out of name ideas.
type Object2 interface {
    SetPhase(phase string)
    GetPhase() string
    SetObservedGeneration(generation int64)
}

The module is experimental and kept intentionally simple: minimal API, minimal dependencies, no feature creep. You can use it as a starting point and adapt the rules or the manager to your CRDs.

Try it in the browser

You can see phase rules in action and experiment with conditions and rule order in the interactive demo, load the templates of build your own rules:

Demo (GitHub Pages): https://debdutdeb.github.io/kubernetes-phase-rules/

The demo lets you define condition types, set their statuses, and define an ordered list of phase rules (with AND/OR and allowed statuses). It computes the resulting phase so you can build intuition for how conditions map to phase and why rule order matters.

Simplifying Tenable.io Agent Deployment in Kubernetes Clusters

Igor Rincon — Wed, 24 May 2023 20:06:50 +0000

Deploying and managing the Tenable.io agent in a Kubernetes cluster nodes can be a manual and time-consuming when you want to guarantee that agents are automatically installed in new nodes and avoid permanment writing of files inside the node's storage. In this article, we will introduce a solution that automates the deployment and management of the Tenable.io agent as a DaemonSet in a Kubernetes cluster. This solution simplifies the installation process and provides visibility into the security posture of your cluster.

The Problems

Before we dive into the solution, let's understand the problems that we're trying to cover with this solution:

1. First problem:

"I need to start a manual process of installing the tenable.io agent everytime that a node joins my cluster"

2. Second problem:

"I need to implement tenable.io agent in a pod and use this pod to scan the node filesystem"

3. Third problem

"I don't want to have a process writing permanent files in my node's storage"

Our way to solve it:

Github Repository: https://github.com/RocketChat/TenableAgent-Daemonset

Having tenable.io agent implemented as a kubernetes Daemonset can be a solution to the problems mentioned above. It automates the deployment of the Tenable.io agent as a DaemonSet in a Kubernetes cluster and streamlines the process of scanning the node's filesystem without writing permanent files in the node's storage, if the DaemonSet is gone, the files will be gone. To solve it, we create a k8s manifest with the specifications:

Unprivileged DaemonSet POD: The kubernetes manifest creates an unprivileged DaemonSet pod that runs the Tenable.io agent. This pod will be deployed on every node in the Kubernetes cluster.
Filesystem Access: To enable the Tenable.io agent to scan the node's filesystem, the manifest changes the filesystem root of the agent process to the node's filesystem. This ensures that the agent has the necessary access to perform security scans effectively
Ephemeral Filesystem Writing: It's simple: If the Daemonset is gone, the files will be removed from the node's filesystem.

Deployment Steps

To deploy this manifest and start using the Tenable.io agent in your Kubernetes cluster, follow these steps:

Prerequisites

Before getting started, make sure you have the following prerequisites:

Sealed Secrets implemented in your cluster.
kubectl installed and configured to access your cluster.
A Tenable.io link key to link the agent with your Tenable.io Manager.

Preparing files and applying it

Create a Sealed Secrets key inside your cluster. Replace 'YOUR TENABLE KEY GOES HERE' with your Tenable.io sync token and convert it to base64 format:

echo -n '{"link":{"host": "cloud.tenable.com","port": 443,"key": "YOUR TENABLE KEY GOES HERE","name": "$NODE_NAME", "groups": ["agent-group"]}}' | base64

Insert the base64 encoded string in the 'secrets.yaml' file. Use 'kubeseal' to encrypt it:

cat secret.yaml | kubeseal \
    --controller-namespace kube-system \
    --controller-name sealed-secrets \
    --format yaml \
    > sealed-secret.yaml

Apply the sealed secrets to your cluster:

kubectl apply -f sealed-secret.yaml

Deploy the DaemonSet using the following command:

kubectl apply -f manifest/tenable-pod.yaml

After a few minutes, you should be able to see your node information in the tenable.io sensors list.

If you think that you have something to improve this solution, feel free to PR. We will review it and approve as soon as possible.

Implementing Client SSL Authentication

Aaron Ogle — Wed, 24 May 2023 13:06:19 +0000

Are you looking to add an extra layer of security to access Rocket.Chat? One way to do this is by implementing client SSL certificate authentication. This authentication method requires clients to present a valid SSL certificate to authenticate themselves to the server.

In this post, we will walk through the steps to set up client SSL certificate authentication using Nginx.

Prerequisites

A server running Ubuntu
- Allow HTTP/HTTPS/ssh in security group
- Create a public IP and associate it.
A domain
Domain pointed to the server

Step 1: Install Docker

Lets do a quick and easy install of Docker if you haven't already.

curl -L https://get.docker.com | sh

Now Lets add your user to the docker group so you don't have to use sudo before every docker command.

sudo usermod -aG docker $USER

Normally here we'd say logout and back in.. but I don't want to mess with it so I use:

newgrp docker

Step 2: Install Rocket.Chat

Now that we have Docker installed lets get Rocket.Chat up and running.

Start off with creating a rocketchat directory and grabbing the docker-compose file:

mkdir rocketchat && cd "$_"
curl -L https://go.rocket.chat/i/docker-compose.yml -O

Next lets fire it up.

docker compose up -d

If impatient or only came here to install Rocket.Chat you could access on port 3000 if your firewall is open. But I suspect you came here for seeing how to do client SSL. So lets carry on!

Step 3: Install Nginx

sudo apt install -y nginx

Step 4: Install Certbot

To help us get a valid certificate we are going to use letsencrypt but using a tool called certbot. This will help us make sure to keep the certificate valid as well.

sudo snap install --classic certbot

Now use certbot to generate and plug everything up for letsencrypt and nginx:

sudo certbot --nginx

You’ll be asked to provide a valid email and the domain set.

Step 5: Generate Certificate Authority (CA) Certificates

In order to do client SSL Authentication we’re going to need a CA.

Generate a key for your CA:

openssl genrsa -des3 -out ca.key 4096

Generate a certificate for your CA:

openssl req -new -x509 -days 365 -key ca.key -out ca.crt

Note what you’ve entered for Country, State, Locality, and Organization; you’ll want these to match later when you renew the certificate.
Do not enter a common name (CN) for the certificate.
Email can be omitted.
Note renewing certificate involves running the same command. If you need to remember what options you chose you can run:

openssl x509 -in ca.crt -noout -text

Move CA cert

To: /etc/ssl/private/client-cert-ca.crt

Update Nginx config

We need to add CA cert, turn on client ssl authentication and add location block:

ssl_client_certificate /etc/ssl/private/client-cert-ca.crt;
ssl_verify_client optional;

location / {
   if ($ssl_client_verify != SUCCESS) {
     return 403;
   }

    proxy_pass http://localhost:3000;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Nginx-Proxy true;
    proxy_redirect off;
  }

Step 6: Issue Client SSL Certificates for users

You can have your users perform most of these steps if you want. But the following are the steps needed to create a certificate to present as client authentication.

Generate key for user

openssl genrsa -des3 -out user.key 4096

Generate a CSR

openssl req -new -key user.key -out user.csr

A number of questions will be asked; answer each one, including the Common Name (CN) and email address. The CSR needs to be sent to the admin (or you if you are doing this for the user).

Sign CSR with CA

As the admin, take the CSR given to you or generated by you and sign the CSR and create valid certificate:

openssl x509 -req -days 365 -in user.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out user.crt

You’ll want to increment the serial number with each signing. Once the certificate expires, a new CSR doesn’t need to be recreated; the same one can be signed, which will create a new certificate tied to that public key.

Return Certificate

The signed certificate (user.crt) can now be sent back to the user along with the CA cert(ca.crt).

To be able to use in browsers and mobile generate a pkcs #12 using the user cert and key along with the Ca:

openssl pkcs12 -export -out user.pfx -inkey user.key -in user.crt -certfile ca.crt

Beware if you intend to install on Mac or iOS, you may need to use an older version of OpenSSL. More info here: https://developer.apple.com/forums/thread/697030?answerId=710429022#710429022

Step 7: Access Rocket.Chat using Client SSL Certificate

To access your application with client certificate authentication:

On iOS:

Add the file on Files app (depending on what you do, iOS will try to install it on the whole OS. e.g. copying from airdrop)
Go to new server screen and try the server URL just to confirm (an error message should show because you haven't applied the cert yet)
Tap apply your certificate on the bottom of the screen and select it from the Files app
Try again, and it should navigate to the workspace info

On Android:

Install the certificate
Go to new server screen and try the server URL just to confirm (an error message should show because you haven't applied the cert yet)
Tap apply your certificate, and the OS should prompt you to select a cert
Select it
Tap connect, and it should navigate to the workspace info

On Firefox:

Open Firefox and click on the three horizontal lines in the top-right corner of the window.
Select "Preferences".
In the left-hand menu, click on "Privacy & Security".
Scroll down to the "Certificates" section and click on "View Certificates".
Click on the "Your Certificates" tab.
Click on "Import".
Browse to the location of your client certificate file and select it.
Enter the password for the certificate if prompted.
Click "OK".
Your client certificate should now be imported and ready to use in Firefox.
Visit the address and you should be prompted to select the certificate.

Congratulations! You have successfully set up client SSL certificate authentication for Rocket.Chat using Nginx.

Extremely useful Reference: https://fardog.io/blog/2017/12/30/client-side-certificate-authentication-with-nginx/