zitadel-resources-operator/README.md

Zitadel Resources Operator

A Kubernetes operator for managing Zitadel resources across single and multi-cluster environments.

Description

The Zitadel Resources Operator enables declarative management of Zitadel resources through Kubernetes custom resources. It supports both traditional same-cluster deployments and cross-cluster scenarios where resources can reference Zitadel entities across different Kubernetes clusters.

Key Features

• Cross-Cluster Support: Reference Zitadel resources across different Kubernetes clusters using direct Zitadel IDs
• Declarative Management: Define Zitadel resources as Kubernetes custom resources
• Automatic Reconciliation: Ensures desired state is maintained in Zitadel
• Flexible Reference Types: Support for both Kubernetes object references and direct Zitadel ID references
• Resource Hierarchy: Connection → Organization → Project → Applications
• Validation: Built-in validation rules to ensure correct resource configuration

Architecture

Resource Hierarchy

The operator follows this resource hierarchy:

Connection (Zitadel instance connection)
    ↓
Organization (Zitadel organization)
    ↓
Project (Zitadel project)
    ↓
Applications (OIDCApp, APIApp, MachineUser, etc.)

Supported Resources

• Connection: Zitadel instance connection configuration
• Organization: Zitadel organization management
• Project: Zitadel project with roles and grants
• OIDCApp: OIDC application configuration
• APIApp: API application configuration
• MachineUser: Machine user management
• Action: Custom actions
• Flow: Flow configurations

Cross-Cluster Support

The operator supports two reference modes for flexible deployment scenarios:

Same-Cluster References (Traditional)

Use Kubernetes object references when resources exist in the same cluster:

apiVersion: zitadel.github.com/v1alpha1
kind: Project
metadata:
  name: my-project
  namespace: default
spec:
  organizationRef:
    name: my-organization
    namespace: default
  projectName: my-project

Cross-Cluster References (New)

Use direct Zitadel ID references when resources span multiple clusters:

apiVersion: zitadel.github.com/v1alpha1
kind: Project
metadata:
  name: my-project
  namespace: workload-dev
spec:
  organizationRef:
    id: "367990024731427343"
    connectionRef:
      name: mgmt-prod-connection
      namespace: zitadel-system
  projectName: my-project

Reference Validation

The operator enforces these validation rules:

• Mutual Exclusivity: Must provide either name (K8s reference) or id (Zitadel ID), but not both
• Required Field: At least one reference method must be provided
• Connection Requirement: When using id, connectionRef.name is required

Usage Examples

Complete Cross-Cluster Setup

1. Create Connection in Management Cluster

apiVersion: zitadel.github.com/v1alpha1
kind: Connection
metadata:
  name: mgmt-prod-connection
  namespace: zitadel-system
spec:
  host: id.corredorconect.com
  secure: true
  authentication:
    pat:
      tokenSecretKey:
        name: mgmt-prod-secret
        key: pat

2. Create Organization in Management Cluster

apiVersion: zitadel.github.com/v1alpha1
kind: Organization
metadata:
  name: corredorconect
  namespace: zitadel-system
spec:
  connectionRef:
    name: mgmt-prod-connection
    namespace: zitadel-system
  organizationName: corredorconect

3. Create Project in Workload Cluster (Cross-Cluster)

apiVersion: zitadel.github.com/v1alpha1
kind: Project
metadata:
  name: seguros-dev
  namespace: zitadel-resources-operator
spec:
  organizationRef:
    id: "367990024731427343"
    connectionRef:
      name: zitadel-connection
      namespace: zitadel-resources-operator
  projectName: segurOS-dev
  projectRoleAssertion: true
  projectRoleCheck: true
  hasProjectCheck: true
  roles:
    - key: admin
      displayName: Admin
      group: system

4. Create OIDC App in Workload Cluster (Cross-Cluster)

apiVersion: zitadel.github.com/v1alpha1
kind: OIDCApp
metadata:
  name: my-oidc-app
  namespace: workload-dev
spec:
  projectRef:
    id: "987654321098765432"
    connectionRef:
      name: zitadel-connection
      namespace: zitadel-resources-operator
  oidcAppName: my-app
  redirectUris:
    - https://example.com/callback
  responseTypes:
    - OIDC_RESPONSE_TYPE_CODE
  grantTypes:
    - OIDC_GRANT_TYPE_AUTHORIZATION_CODE
  appType: OIDC_APP_TYPE_WEB
  authMethodType: OIDC_AUTH_METHOD_TYPE_BASIC

Reference Types

OrganizationRef

References an organization either by Kubernetes object name or direct Zitadel ID.

Fields:

• name (string): Kubernetes object name (same-cluster)
• id (string): Direct Zitadel organization ID (cross-cluster)
• connectionRef (ConnectionRef): Connection for cross-cluster references
• Standard ObjectReference fields: namespace, kind, apiVersion, etc.

Validation:

• Must provide either name or id, but not both
• When using id, connectionRef.name is required

ProjectRef

References a project either by Kubernetes object name or direct Zitadel ID.

Fields:

• name (string): Kubernetes object name (same-cluster)
• id (string): Direct Zitadel project ID (cross-cluster)
• connectionRef (ConnectionRef): Connection for cross-cluster references
• Standard ObjectReference fields: namespace, kind, apiVersion, etc.

Validation:

• Must provide either name or id, but not both
• When using id, connectionRef.name is required

Getting Started

Prerequisites

• Kubernetes cluster (v1.25+)
• kubectl configured to communicate with your cluster
• Zitadel instance with appropriate credentials

Installation

1. Clone the repository:

git clone <repository-url>
cd zitadel-resources-operator

2. Install CRDs:

make install

3. Deploy the operator:

make deploy IMG=<your-image-registry>/zitadel-resources-operator:tag

4. Verify installation:

kubectl get pods -n zitadel-resources-operator-system

Configuration

Create a Connection resource to authenticate with your Zitadel instance:

apiVersion: zitadel.github.com/v1alpha1
kind: Connection
metadata:
  name: zitadel-connection
  namespace: zitadel-resources-operator
spec:
  host: your-zitadel-instance.com
  secure: true
  authentication:
    pat:
      tokenSecretKey:
        name: zitadel-credentials
        key: pat

Create the secret with your credentials:

kubectl create secret generic zitadel-credentials \
  --from-literal=pat=your-zitadel-pat-token \
  -n zitadel-resources-operator

Development

Running Locally

1. Install CRDs:

make install

2. Run the operator locally:

make run

Building and Testing

1. Build the operator:

make build

2. Run tests:

make test

3. Generate manifests:

make manifests

Modifying API Definitions

When modifying API types, regenerate the CRDs:

make manifests
make install

Troubleshooting

Common Issues

Issue: Organization.zitadel.github.com "" not found

• Solution: Ensure you're using either name or id in references, not both. Check validation rules.

Issue: Cross-cluster references not working

• Solution: Verify that connectionRef is properly specified when using id references.

Issue: Resources not reconciling

• Solution: Check operator logs: kubectl logs -n zitadel-resources-operator-system deployment/zitadel-resources-operator-controller-manager

Debug Mode

Enable debug logging by setting the log level:

kubectl set env deployment/zitadel-resources-operator-controller-manager \
  -n zitadel-resources-operator-system \
  --containers=manager \
  LOG_LEVEL=debug

Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Development Workflow

1. Make changes to the code
2. Run tests: make test
3. Generate manifests: make manifests
4. Build locally: make build
5. Test in cluster: make install && make run

License

Copyright 2024.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.