How to Restart a Service

This guide shows you how to restart an unresponsive Axual component, and why an Apache Kafka broker is restarted through Strimzi rather than by deleting its pod.

Type

How-to guide

Goal

Restart a component that Kubernetes reports as healthy but that has stopped responding.

Audience

Platform Operator who can delete pods and trigger rollouts in the target namespace.

When to use

Use this guide as a last resort, once you have established that a service is not responding and you have gathered what you need to diagnose why.
A restart destroys the state you would diagnose from. Capture the pod’s events and logs first, with How to Inspect Kubernetes Workloads, because a restarted pod cannot tell you why it was stuck.

Contents

The sections below cover each task in this guide:

Prerequisites

Confirm the following before you begin.

Access and permissions required

You need the following access and permissions:

  • Permission to delete pods and trigger deployment rollouts in the namespace.

  • Permission to annotate Strimzi resources, for the Apache Kafka broker path.

Tools and versions required

You need the following tools:

  • kubectl >= 1.28, configured for the target cluster.

Resources that must exist before starting

The following must already exist:

  • A diagnosis attempt, or a decision to stop diagnosing. Restarting first removes the evidence.

Identify the pod to restart

List the pods and pick out the one backing the unresponsive service. Each platform component runs as part of a replica set, so Kubernetes recreates the pod as soon as it goes.

Replace every <VALUE> placeholder with your own value before running a command. 
kubectl get pods --namespace kafka

Restart a platform component

Roll the deployment rather than deleting the pod where you can, because a rollout brings the replacement up before taking the old one down.

kubectl rollout restart deployment/<DEPLOYMENT_NAME> --namespace kafka

Deleting the pod also works, and is the option when the workload is not a Deployment:

kubectl delete pod <POD_NAME> --namespace kafka

Confirm the replacement reaches Running and that the service responds again.

Restart an Apache Kafka broker

Never delete an Apache Kafka broker pod. Deleting one bypasses the Strimzi operator. That operator keeps the cluster’s replicas in sync during a roll, so a manual delete risks under-replicated partitions.

Annotate the resource instead and let Strimzi do the roll:

kubectl annotate strimzipodset <PODSET_NAME> --namespace kafka strimzi.io/manual-rolling-update=true

Strimzi then restarts the broker pods one at a time, waiting for each to rejoin before moving to the next. The Strimzi documentation covers the annotation in full, including how to roll a single pod.