#Quick Start

This document will help you quickly understand and use the Connectors system.

#Introduction

#Applicable Scenarios

The Connectors system provides a unified way to securely manage connections to external systems across your Kubernetes cluster. By using connectors, you can:

• Centralize credential management for external services
• Eliminate hardcoded credentials in application code
• Ensure consistent access patterns across your organization
• Monitor and audit service connections in one place

This guide uses GitHub as an example, but the same principles apply to connecting to other services.

#Estimated Reading Time

10-15 minutes

#Notes

• This quick start assumes you already have the Connectors Operator installed and a ConnectorsConfig reconciled to Ready (the operator creates one automatically — see the Installation Guide). The default install enables every component, including core and git, which are required for this guide.
• You need a GitHub account and a Personal Access Token (PAT) with appropriate permissions.
• Connector status reflects the health and accessibility of the connection.

#Prerequisites

• Kubernetes cluster with the Connectors Operator installed and a ConnectorsConfig reconciled to Ready. The default install enables the core and git components needed for this guide.
• kubectl configured to communicate with your cluster
• GitHub account and valid Personal Access Token (PAT)
• Basic knowledge of Kubernetes resources

#Process Overview

#Steps to Operate

#Step 1: Verify Required Components

Before creating a GitHub connector, verify that the connector infrastructure is properly installed in your cluster.

1. Check that the ConnectorsConfig is reconciled to Ready:

   kubectl get connectorsconfig -A

   READY should report True. For per-component phases, run kubectl describe connectorsconfig connectors-config -n <namespace>.

2. Verify that the Git ConnectorClass exists:

   kubectl get connectorclass git

   If the Git ConnectorClass is not found, the git component is disabled or has not finished installing. Enable it on ConnectorsConfig (spec.components.git.enabled: true) and re-check — see the Installation Guide for the configuration syntax.

#Step 2: Create Authentication Secret

Create a Kubernetes Secret containing the credentials for GitHub.

1. Execute the following command to create a Secret with your GitHub credentials:

   kubectl create secret generic github-auth \
     --namespace default \
     --type=kubernetes.io/basic-auth \
     --from-literal=username=your-github-username \
     --from-literal=password=your-github-token

   Replace your-github-username with your GitHub username and your-github-token with your GitHub Personal Access Token.

2. Verify that the Secret was successfully created:

   kubectl get secret github-auth -n default

#Step 3: Create GitHub Connector

Create a connector to GitHub using the Git ConnectorClass.

1. Save the following YAML as github-connector.yaml:

   apiVersion: connectors.alauda.io/v1alpha1
   kind: Connector
   metadata:
     name: github-connector
     namespace: default
   spec:
     connectorClassName: git
     address: "https://github.com"
     auth:
       name: basicAuth
       secretRef:
         name: github-auth
         namespace: default

2. Apply the connector:

   kubectl apply -f github-connector.yaml

#Step 4: Verify Connector Status

After creating the connector, check its status to ensure it's functioning correctly.

1. Use the following command to check the connector status:

   kubectl get connector github-connector -n default

2. To view detailed status information, use:

   kubectl get connector github-connector -n default -o yaml

#Expected Results

After successfully completing all steps, you will see the following results:

1. The GitHub connector resource status shows as "Ready":

   NAME               CLASS   ADDRESS              READY   AGE
   github-connector   git     https://github.com   True    2m

2. All conditions in the detailed status information are "True":

   status:
     conditions:
     - type: ConnectorClassReady
       status: "True"
     - type: SecretReady
       status: "True"
     - type: LivenessReady
       status: "True"
     - type: AuthReady
       status: "True"
     - type: ProxyServiceReady
       status: "True"
     - type: Ready
       status: "True"

3. If the connector has proxy functionality configured, you will also see a proxy address in the status:

   status:
     proxy:
       httpAddress:
         url: http://c-github-connector.default.svc.cluster.local

Now, you have successfully created a GitHub connector and verified that it works.

Your applications can use this connector to securely access GitHub repositories without embedding credentials directly in application code.

#Troubleshooting

If your connector doesn't reach the "Ready" status, check the following:

1. ConnectorClass Availability: Ensure the Git ConnectorClass exists:

   kubectl get connectorclass git

   If it doesn't exist, the git component is disabled or has not finished installing on ConnectorsConfig. See the Installation Guide for the configuration syntax.

2. Authentication Configuration: Ensure the credentials in the Secret are correct and have appropriate permissions.

3. Repository Accessibility: Verify that the repository specified in the auth params exists and is accessible with the provided credentials.

4. Check Controller Logs: Review the connector controller logs for detailed error information:

   kubectl logs -n connectors-system -l app.kubernetes.io/name=connectors-controller-manager

#Next Steps

Now that you've created your first connector, you can:

• Create connectors for other Git services (GitLab, Harbor, etc.)
• Configure applications to use the connector for secure access to Git repositories