#Installation Guide

This guide installs the Connectors system on a Kubernetes cluster. A single ConnectorsConfig resource drives the whole install — the Connectors Operator reconciles it into one managed child CR per component (ConnectorsCore, ConnectorsGit, ConnectorsOCI, …).

#Introduction

The Connectors system has a modular architecture composed of:

• Connectors Operator — the management component that reconciles ConnectorsConfig and installs every other component.
• ConnectorsConfig — the single cluster-wide resource that declares which components are installed.
• Connectors components — ConnectorsCore plus optional per-tool components.

Administrators only need to manage ConnectorsConfig. The operator creates, updates, and deletes every component child resource derived from it.

#Prerequisites

• A Kubernetes cluster.
• A kubectl CLI configured to communicate with the cluster.
• Cluster-admin permissions.
• The Alauda DevOps Connectors operator package available on the platform's OperatorHub.

#Pod Security Requirements

Kubernetes enforces Pod Security Standards (PSS) at the namespace level. The Connectors system uses two namespaces with different privilege requirements:

If the components namespace is configured with restricted or baseline, the CSI driver fails to start. See Troubleshooting for the recovery procedure.

#How ConnectorsConfig Works

ConnectorsConfig is the cluster-wide control resource for the whole Connectors install. Platform administrators edit ConnectorsConfig; the operator reconciles it into per-component child CRs. Do not edit the managed child CRs (ConnectorsCore, ConnectorsGit, …) directly — the operator overwrites them on the next reconcile.

#Cluster Singleton

Although ConnectorsConfig is namespaced, the admission webhook lists across all namespaces on every create and rejects the request if any other ConnectorsConfig already exists — including one that is currently being deleted (its finalizer may still be cleaning up child CRs). This enforces a cluster-wide singleton: every managed child CR belongs to exactly one parent, and the cluster has a single source of truth for which components are installed.

#Auto-creation on Operator Startup

When the operator starts and no ConnectorsConfig exists, it creates a default one with every supported component enabled at defaults. The target namespace is resolved with the following priority:

1. The namespace of an existing ConnectorsCore — preserved on the upgrade path so the managed children land where the previous standalone install lived. See Migration to ConnectorsConfig in the upgrade guide.
2. The operator's own install namespace (SYSTEM_NAMESPACE injected via the Downward API) — used for fresh installs.

The bootstrap runs as a leader-elected runnable, so it re-executes on every leader election (first deploy, rolling restart, leader pod replacement). The work is idempotent — if a ConnectorsConfig already exists, the bootstrap exits without touching the cluster state.

Confirm the bootstrap ran by looking for BootstrapStarted and BootstrapCompleted events:

kubectl describe connectorsconfig connectors-config -n <namespace>

#Deletion Cascade

Deleting the ConnectorsConfig triggers cascading deletion of every managed child CR through the owner reference (Controller=true, BlockOwnerDeletion=true). The parent's finalizer prevents ConnectorsConfig itself from being removed until every child CR has finished its own finalizer, so deletion is safe even when a component takes time to drain.

#Install Flags

spec.installFlags lets administrators opt out of a small set of install-time behaviors. Each entry is keyed by a stable flag name; the value's shape is documented per flag.

Available flags:

Example — restrict Pipeline Integration to schema-version 2 and below across the cluster:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
spec:
  installFlags:
    pipeline-integration: "<=2"   # install v1 and v2; skip v3+

For pipeline-integration the value is a string. Supported basic forms:

Compound forms such as "<2 || >=4", "!=2", ">=1, <=3", and wildcard / tilde / caret bounds ("1.x", "~1.2", "^1.2") are also accepted — the value is parsed as a full semver constraint expression. The basic forms above cover the common case.

The same flag may also be set per component on ConnectorsConfig (e.g. spec.components.harbor.spec.installFlags) to override the cluster-wide value for that component only.

#Step 1: Install the Connectors Operator

Install the Alauda DevOps Connectors operator from the platform's OperatorHub — do not create the operator Subscription by hand.

1. Log in to the platform as an administrator.
2. Navigate to Administrator → Marketplace → OperatorHub.
3. Search for Alauda DevOps Connectors and open the operator's detail page.
4. Click Install, then choose:
   • Channel — pick the release channel you intend to track.
   • Install namespace — the operator's own namespace (connectors-operator is the recommended default; any namespace works).
   • Approval strategy — Automatic or Manual, per your upgrade policy.
5. Approve the install plan if you chose Manual.
6. Wait until the operator's subscription reports Succeeded on the operator detail page.

Once the operator is reported as Ready, verify the controller pod and the expected CRDs from the command line:

kubectl get pods -n connectors-operator

NAME                                                  READY   STATUS    RESTARTS   AGE
connectors-operator-controller-manager-xxxxxx-xxxxx   2/2     Running   0          1m

kubectl get crds | grep operator.connectors.alauda.io

You should see CRDs including connectorsconfigs.operator.connectors.alauda.io, connectorscores.operator.connectors.alauda.io, and one CRD per supported component.

#Step 2: Install Connectors Components

Components are installed through a single ConnectorsConfig resource. See Cluster Singleton for the one-per-cluster constraint.

#Default Install (Recommended)

When the operator starts and no ConnectorsConfig exists, it automatically creates a default one, enabling every supported component at defaults:

apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
  namespace: connectors-operator   # fresh install: the operator's install namespace
spec: {}

The target namespace is not always the operator's install namespace. On the upgrade path, if a ConnectorsCore already exists, the bootstrap reuses that namespace so the new managed children land alongside the existing standalone install. See Auto-creation namespace priority for the full resolution rule.

Verify the install converges (replace the namespace if the bootstrap picked a different one):

kubectl get connectorsconfig -A
kubectl wait --for=condition=Ready connectorsconfig/connectors-config \
  -n connectors-operator --timeout=600s

To choose a different install namespace, or to customize the spec before the components are created, pre-create ConnectorsConfig yourself with the Manual Install procedure below before the operator starts. The bootstrap detects the existing ConnectorsConfig and skips its own default creation.

#Manual Install

If automatic creation is disabled, create the ConnectorsConfig yourself in the namespace that should host the components. The namespace name is your choice — connectors-system is used below as an example. Whichever namespace you create the ConnectorsConfig in is where every component child CR will be created.

kubectl create namespace connectors-system

cat <<EOF | kubectl apply -f -
apiVersion: operator.connectors.alauda.io/v1alpha1
kind: ConnectorsConfig
metadata:
  name: connectors-config
  namespace: connectors-system
spec: {}
EOF

#Verify the Installation

The commands below use connectors-operator — the default-install namespace. If you created the ConnectorsConfig yourself in a different namespace (the Manual Install path above), substitute that namespace instead.

Check the roll-up condition:

kubectl get connectorsconfig -A
kubectl describe connectorsconfig connectors-config -n connectors-operator

status.conditions[Ready]=True indicates every enabled component finished installing. For per-component phases and the meaning of each condition, see Status & Phases.

List the ConnectorClass resources each component registers — these are the per-tool integration types the Connectors system exposes (see ConnectorClass):

kubectl get connectorclass

#Step 3: Customize Your Install (Advanced)

spec: {} enables every component with defaults. Most installs need nothing else. Use this section when you need to opt components out, tune feature flags, or override workload settings.

ConnectorsConfig.spec carries two kinds of settings:

• spec.components — a map keyed by short component name (core, git, github, gitlab, oci, harbor, k8s, maven, npm, pypi, sonarqube, nexus, jfrog). Each value is a ComponentConfig with enabled (true by default; core.enabled: false is rejected) and spec (component-specific configuration, same schema as the corresponding standalone component CR). Components not listed in the map are enabled with default settings.
• Cluster-wide defaults at the spec root — registry, labels, annotations, and installFlags live directly under spec and apply to every component as defaults. Merge precedence is component value wins — a key set on both the spec root and the component falls back to the spec-root value only when the component omits it.

The five examples below cover the most common customizations. For the full per-component schema, refer to the ConnectorsConfig CRD reference.

#Disable Components

spec:
  components:
    sonarqube: { enabled: false }
    nexus:     { enabled: false }

#Set Feature Flags on core

featureFlags toggles optional behaviours on ConnectorsCore. See Feature Flags for the full list of supported flags and what each one changes.

spec:
  components:
    core:
      spec:
        featureFlags:
          enable-multi-connector: "true"
          enable-custom-ca-certs: "true"

#Override the Image Registry (Cluster-wide)

spec:
  registry: registry.example.com/connectors

The registry prefix is applied to every component's workload images unless a component overrides it locally with its own spec.components.<name>.spec.registry.

#Tune Workload Replicas and Resources

Every component embeds the same workloads schema. The deployment name varies per component; discover it with:

kubectl -n <components-namespace> get deploy

The pattern below applies uniformly to core, git, gitlab, github, oci, harbor, k8s, maven, npm, pypi, sonarqube, nexus, and jfrog:

spec:
  components:
    git:
      spec:
        workloads:
          - name: connectors-git-plugin
            replicas: 2
            template:
              spec:
                containers:
                  - name: plugin
                    resources:
                      limits:   { cpu: 300m, memory: 256Mi }
                      requests: { cpu: 100m, memory: 128Mi }

#Expose the OCI Proxy Externally

ConnectorsOCI supports three exposure modes. Pick one:

# ClusterIP (default): in-cluster access only
spec:
  components:
    oci:
      spec: {}

# NodePort: external access via a node IP
spec:
  components:
    oci:
      spec:
        expose:
          type: NodePort
          domain: 192.168.1.100
          nodePort:
            port: 30080

# Ingress: external access via a hostname
spec:
  components:
    oci:
      spec:
        expose:
          type: Ingress
          domain: connectors.proxy.example.com

#Status & Phases

ConnectorsConfig.status reports both a roll-up cluster condition and per-component state.

#Conditions

#Per-component Phases

status.components maps component name to a phase:

#Uninstall

Removing the ConnectorsConfig cascades into every managed component (replace the namespace with the one you used at install time):

kubectl delete connectorsconfig connectors-config -n connectors-operator

A finalizer on ConnectorsConfig prevents the parent from being removed until every child CR has finished draining, so deletion is safe even when a component takes time to clean up.

To also remove the operator itself, look up the actual Subscription name first — OperatorHub names it after the operator package, which may differ across platforms:

kubectl get subscription -n connectors-operator
kubectl delete subscription -n connectors-operator <subscription-name>
kubectl delete namespace connectors-operator

If you installed the components in a separate namespace (Manual Install), delete that namespace as well.

#Troubleshooting

#connectors-csi Is Not Ready

If daemonset/connectors-csi is not ready, check the pod events:

Error creating: pods "connectors-csi-d4r6r" is forbidden: violates
PodSecurity "baseline:latest": non-default capabilities (container
"driver" must not include "SYS_ADMIN" in securityContext.capabilities.add),
host namespaces (hostNetwork=true), hostPath volumes (volumes
"socket-dir", "mountpoint-dir", "registration-dir") ...

The components namespace's Pod Security level is too restrictive for the CSI driver. Set it to privileged, update the namespace labels, and restart the connectors-csi DaemonSet. See Pod Security Requirements.

#A Component Is Stuck in Failed

status.components.<name>.message is the first place to look. The controller emits a ComponentConflict Warning event on the parent each time a component transitions into this state. The two common causes both come from stale standalone CRs left over from an upgrade:

• Cluster-wide conflict — a CR of the same kind exists in another namespace (or under a different name in the same namespace). The message lists every conflicting namespace/name. Delete the offending CR(s) and the controller recovers on the next reconcile.
• Unmanaged CR at the deterministic name — a CR already exists at the expected name and namespace but does not carry the ManagedBy=connectorsconfig label. The controller refuses to adopt it (message: child CR ... already exists but is not managed by ConnectorsConfig — delete it manually to allow adoption). Delete the unmanaged CR and the controller creates a new managed child on the next reconcile.

If you are mid-upgrade from a pre-ConnectorsConfig release, see Migration to ConnectorsConfig for context.

#Related Documentation

• Upgrading the Connectors Operator — includes the one-way migration from pre-ConnectorsConfig installs.
• Feature Flags — the full list of flags configurable through spec.components.core.spec.featureFlags.
• Quick Start — create your first Connector after install.
• Architecture overview — how the components fit together.
• ConnectorsConfig CRD reference.