Troubleshoot an Axual Connect Deployment

This guide shows you how to gather the state needed to diagnose an Axual Connect problem, how to reach its API when it is not publicly exposed, and what to do about a corrupted Connect-Application certificate.

Type

How-to guide

Goal

Establish why an Axual Connect deployment or one of its connectors is failing.

Audience

Platform Operator with read access to the namespace Axual Connect runs in.

When to use

Use this guide when a worker or a connector fails, before changing any configuration.

Axual Connect runs as a plain Kubernetes Deployment, unlike Kafka Connect, which Strimzi manages as a KafkaConnect Custom Resource (CR). So use kubectl against the Deployment and its pods directly.

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:

  • Read access to the namespace Axual Connect runs in, enough to describe the Deployment and Service and to read pod logs.

  • Permission to port-forward a Service in that namespace, for the API check.

  • A Tenant Admin account in Self-Service, for the certificate re-upload only.

Tools and versions required

You need the following tools:

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

  • curl and jq, for reading the Connect API response.

Resources that must exist before starting

The following must already exist:

  • An Axual Connect release installed by How to Deploy Axual Connect, whether or not it is healthy.

  • The tenant and instance short names, which every command below is keyed on.

Collect diagnostics before investigating

Gather the Deployment’s configuration, Pod state, and recent logs before diagnosing any specific failure.

Replace every <VALUE> placeholder with your own value before running a command. <TENANT>, <INSTANCE> and <NAMESPACE> are the cluster’s real short names, for example axual, local and kafka.

The three commands below cover every scenario in this guide:

# Effective Deployment spec (the values.yaml used to deploy the Helm chart)
kubectl --namespace <NAMESPACE> describe deployment <TENANT>-<INSTANCE>-axual-connect

# Pod state and events
kubectl --namespace <NAMESPACE> get pods -l app.kubernetes.io/name=axual-connect

# Most recent logs
kubectl --namespace <NAMESPACE> logs -f --tail 2000 deployment/<TENANT>-<INSTANCE>-axual-connect

You can run the equivalent lookups interactively with k9s if you prefer a terminal interface to kubectl.

The Axual Operations Manager (AOM) sits between Platform Manager and Connect. When the Connect logs alone don’t explain a failure, check the AOM logs for the same request too.
Historical logging is not kept for a Helm-deployed Axual Connect. Configure a central logging system and scrape the Axual Connect logs into it if you need log retention beyond the current Pod’s lifetime.

Check the API endpoint

The Connect API must not be exposed publicly, so reach it through a port-forward or an internal-only Ingress.

  1. Find the Service and its port:

    kubectl --namespace <NAMESPACE> describe service <TENANT>-<INSTANCE>-axual-connect

    The port is configurable in values.yaml.

  2. Port-forward the Service to your machine:

    kubectl --namespace <NAMESPACE> port-forward service/<TENANT>-<INSTANCE>-axual-connect 8083:<PORT>

  3. Confirm the worker responds:

    curl -s http://localhost:8083/connector-plugins | jq '.[].class'

    A list of plugin class names confirms the API is reachable and the configured plugins are loaded.

An empty list means the worker is running and its API answers, but no plugin unpacked. That points at the download or the archive rather than at the deployment. How to Install Connect Plugins covers it, and the init container’s logs say which archive failed.

You can also reach the Service from inside any Pod in the same Kubernetes namespace, without a port-forward.

Connect-Application certificate corrupted after upload

Cause: Something saved the certificate file with Windows line endings (carriage return and line feed, CRLF) instead of Unix line endings (line feed, LF). Editing or re-saving the certificate in a standard Windows text editor is the common way this happens.

Fix: Re-export or convert the certificate to use Unix line endings, then re-upload it in Self-Service. Do not edit certificate files with a Windows text editor once exported.