Configuration¶

This guide covers all configuration options for the Git Change Operator, from basic setup to advanced enterprise configurations.

Overview¶

The Git Change Operator can be configured at multiple levels: - Operator-level configuration via command-line flags and environment variables - Resource-level configuration via GitCommit and PullRequest specs - Cluster-level configuration via ConfigMaps and other Kubernetes resources

Operator Configuration¶

Command Line Flags¶

The operator controller supports various command-line flags:

git-change-operator \
  --metrics-bind-addr=:8080 \
  --leader-elect=true \
  --zap-log-level=info \
  --reconcile-interval=30s \
  --max-concurrent-reconciles=10

Environment Variables¶

Configure the operator using environment variables:

# config/manager/manager.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: controller-manager
spec:
  template:
    spec:
      containers:
      - name: manager
        env:
        - name: RECONCILE_INTERVAL
          value: "30s"
        - name: MAX_CONCURRENT_RECONCILES  
          value: "10"
        - name: LOG_LEVEL
          value: "info"
        - name: ENABLE_WEBHOOKS
          value: "true"
        - name: GIT_TIMEOUT
          value: "300s"
        - name: DEFAULT_BRANCH
          value: "main"

Configuration Options¶

Core Settings¶

Flag	Environment Variable	Default	Description
`--metrics-bind-addr`	`METRICS_BIND_ADDR`	`:8080`	Address for metrics server
`--leader-elect`	`ENABLE_LEADER_ELECTION`	`true`	Enable leader election
`--zap-log-level`	`LOG_LEVEL`	`info`	Log level (debug, info, error)
`--reconcile-interval`	`RECONCILE_INTERVAL`	`30s`	Default reconciliation interval
`--max-concurrent-reconciles`	`MAX_CONCURRENT_RECONCILES`	`10`	Max concurrent reconciliations

Git Settings¶

Flag	Environment Variable	Default	Description
`--git-timeout`	`GIT_TIMEOUT`	`300s`	Timeout for Git operations
`--default-branch`	`DEFAULT_BRANCH`	`main`	Default Git branch
`--git-user-name`	`GIT_USER_NAME`	`git-change-operator`	Default Git user name
`--git-user-email`	`GIT_USER_EMAIL`	`[email protected]`	Default Git user email

Resource Settings¶

Flag	Environment Variable	Default	Description
`--enable-webhooks`	`ENABLE_WEBHOOKS`	`true`	Enable admission webhooks
`--webhook-port`	`WEBHOOK_PORT`	`9443`	Webhook server port
`--cert-dir`	`WEBHOOK_CERT_DIR`	`/tmp/k8s-webhook-server/serving-certs`	Webhook certificate directory

Resource Configuration¶

GitCommit Configuration¶

Basic Configuration¶

apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: example-commit
  namespace: default
spec:
  # Required fields
  repository: "https://github.com/myorg/config-repo.git"
  branch: "main"
  message: "Update configuration"

  # Optional configuration
  reconcileInterval: "60s"
  retryPolicy:
    maxRetries: 3
    backoff: "30s"

Advanced Configuration¶

apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: advanced-commit
spec:
  repository: "https://github.com/myorg/config-repo.git"
  branch: "feature/automated-updates"
  message: |
    Automated configuration update

    Updated by: git-change-operator
    Cluster: {{ .cluster.name }}
    Timestamp: {{ .timestamp }}

  # Authentication configuration
  credentials:
    secretName: git-credentials
    usernameKey: username  # default: username
    passwordKey: token     # default: password

  # Git configuration
  author:
    name: "Git Change Operator"
    email: "[email protected]"
  committer:
    name: "Automation System"
    email: "[email protected]"

  # Resource reference configuration
  resourceRef:
    apiVersion: v1
    kind: ConfigMap
    name: app-config
    namespace: default
    path: "config/application.yaml"
    strategy: "template"
    template: |
      # Application Configuration
      # Generated on: {{ .timestamp }}
      app:
        name: {{ .metadata.name }}
        namespace: {{ .metadata.namespace }}
        data:
      {{ range $key, $value := .data }}
        {{ $key }}: {{ $value | quote }}
      {{ end }}

  # Write mode configuration
  writeMode: "overwrite"  # overwrite, append, merge

  # File configuration
  fileMode: "0644"
  directoryMode: "0755"
  createDirs: true

  # Reconciliation configuration
  reconcileInterval: "300s"
  suspend: false

  # Retry configuration
  retryPolicy:
    maxRetries: 5
    backoff: "60s"
    maxBackoff: "600s"
    backoffMultiplier: 2.0

PullRequest Configuration¶

Basic Configuration¶

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: example-pr
spec:
  repository: "https://github.com/myorg/config-repo.git"
  baseBranch: "main"
  headBranch: "automated-update"
  title: "Automated configuration update"
  body: "This PR contains automated updates from the Kubernetes cluster"

Advanced Configuration¶

apiVersion: gco.galos.one/v1
kind: PullRequest
metadata:
  name: advanced-pr
spec:
  repository: "https://github.com/myorg/config-repo.git"
  baseBranch: "main"
  headBranch: "config-update-{{ .timestamp }}"

  # PR metadata
  title: "Configuration update from {{ .cluster.name }}"
  body: |
    # Automated Configuration Update

    This pull request contains automated configuration updates from the Kubernetes cluster.

    ## Changes
    {{ range .changes }}
    - Updated {{ .resource.kind }}/{{ .resource.name }} in namespace {{ .resource.namespace }}
    {{ end }}

    ## Validation
    - [ ] Configuration syntax is valid
    - [ ] No sensitive data is exposed
    - [ ] Changes are backwards compatible

    Generated by: git-change-operator
    Cluster: {{ .cluster.name }}
    Timestamp: {{ .timestamp }}

  # Labels and assignees
  labels:
    - "automated"
    - "configuration"
    - "cluster-sync"
  assignees:
    - "devops-team"
  reviewers:
    - "config-reviewers"

  # PR options
  draft: false
  maintainerCanModify: true

  # Authentication
  credentials:
    secretName: github-token
    tokenKey: token

  # Resource references (same as GitCommit)
  resourceRef:
    apiVersion: v1
    kind: Secret
    name: database-config
    namespace: production
    path: "config/database.yaml"
    strategy: "template"

Authentication Configuration¶

Git Credentials¶

Username/Password Authentication¶

apiVersion: v1
kind: Secret
metadata:
  name: git-credentials
  namespace: default
type: Opaque
data:
  username: dXNlcm5hbWU=  # base64 encoded username
  password: cGFzc3dvcmQ=  # base64 encoded password/token

SSH Key Authentication¶

apiVersion: v1
kind: Secret
metadata:
  name: git-ssh-key
  namespace: default
type: kubernetes.io/ssh-auth
data:
  ssh-privatekey: LS0tLS1CRUdJTi... # base64 encoded SSH private key

GitHub Token Authentication¶

apiVersion: v1
kind: Secret
metadata:
  name: github-token
  namespace: default
type: Opaque
data:
  token: Z2hwX3Rva2Vu...  # base64 encoded GitHub personal access token

Authentication Strategies¶

Per-Resource Authentication¶

# GitCommit with specific credentials
apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: secure-commit
spec:
  repository: "https://github.com/private/repo.git"
  credentials:
    secretName: private-repo-creds
    usernameKey: username
    passwordKey: token

Default Authentication¶

Configure default credentials via environment variables:

# In controller deployment
env:
- name: DEFAULT_GIT_USERNAME
  valueFrom:
    secretKeyRef:
      name: default-git-creds
      key: username
- name: DEFAULT_GIT_PASSWORD
  valueFrom:
    secretKeyRef:
      name: default-git-creds
      key: password

Cluster-Level Configuration¶

ConfigMap Configuration¶

Create a ConfigMap for operator-wide settings:

apiVersion: v1
kind: ConfigMap
metadata:
  name: git-change-operator-config
  namespace: git-change-operator-system
data:
  config.yaml: |
    git:
      timeout: "300s"
      defaultBranch: "main"
      defaultAuthor:
        name: "Git Change Operator"
        email: "[email protected]"

    reconciliation:
      interval: "30s"
      maxConcurrent: 10
      retryPolicy:
        maxRetries: 3
        backoff: "30s"

    webhooks:
      enabled: true
      port: 9443
      certDir: "/tmp/k8s-webhook-server/serving-certs"

    features:
      enableMetrics: true
      enableProfiling: false
      enableTracing: false

Mount the ConfigMap in the controller:

# config/manager/manager.yaml
spec:
  template:
    spec:
      containers:
      - name: manager
        args:
        - --config=/etc/config/config.yaml
        volumeMounts:
        - name: config
          mountPath: /etc/config
          readOnly: true
      volumes:
      - name: config
        configMap:
          name: git-change-operator-config

RBAC Configuration¶

Minimal RBAC¶

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: git-change-operator-manager-role
rules:
# GitCommit and PullRequest resources
- apiGroups: ["gco.galos.one"]
  resources: ["gitcommits", "pullrequests"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
- apiGroups: ["gco.galos.one"]
  resources: ["gitcommits/status", "pullrequests/status"]
  verbs: ["get", "update", "patch"]

# Resources to read for references (minimal example)
- apiGroups: [""]
  resources: ["configmaps", "secrets"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments", "configmaps"]
  verbs: ["get", "list", "watch"]

Extended RBAC for All Resources¶

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: git-change-operator-extended-role
rules:
# Core resources
- apiGroups: [""]
  resources: ["*"]
  verbs: ["get", "list", "watch"]

# Apps resources
- apiGroups: ["apps"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]

# Custom resources (add as needed)
- apiGroups: ["networking.k8s.io"]
  resources: ["*"]
  verbs: ["get", "list", "watch"]

# Operator's own resources
- apiGroups: ["gco.galos.one"]
  resources: ["*"]
  verbs: ["*"]

Performance Configuration¶

Resource Limits¶

Configure appropriate resource limits:

# config/manager/manager.yaml
spec:
  template:
    spec:
      containers:
      - name: manager
        resources:
          limits:
            cpu: 500m
            memory: 512Mi
          requests:
            cpu: 100m
            memory: 128Mi

Scaling Configuration¶

Horizontal Pod Autoscaling¶

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: git-change-operator-hpa
  namespace: git-change-operator-system
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: git-change-operator-controller-manager
  minReplicas: 1
  maxReplicas: 5
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
  - type: Resource
    resource:
      name: memory
      target:
        type: Utilization
        averageUtilization: 80

Vertical Pod Autoscaling¶

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: git-change-operator-vpa
  namespace: git-change-operator-system
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: git-change-operator-controller-manager
  updatePolicy:
    updateMode: "Auto"
  resourcePolicy:
    containerPolicies:
    - containerName: manager
      minAllowed:
        cpu: 100m
        memory: 128Mi
      maxAllowed:
        cpu: 1000m
        memory: 1Gi

Monitoring Configuration¶

Metrics Configuration¶

Enable Prometheus metrics:

# config/prometheus/monitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: git-change-operator-metrics
  namespace: git-change-operator-system
spec:
  endpoints:
  - path: /metrics
    port: http
    interval: 30s
    scheme: http
  selector:
    matchLabels:
      control-plane: controller-manager

Custom Metrics¶

Configure custom metrics in the operator:

# ConfigMap configuration
data:
  config.yaml: |
    metrics:
      enabled: true
      port: 8080
      path: "/metrics"
      interval: "30s"
      customMetrics:
        - name: "git_operations_total"
          help: "Total number of Git operations"
          type: "counter"
        - name: "git_operation_duration_seconds"
          help: "Duration of Git operations in seconds"
          type: "histogram"
        - name: "resource_references_total"
          help: "Total number of resource references processed"
          type: "counter"

Logging Configuration¶

Log Levels¶

Configure different log levels:

env:
- name: LOG_LEVEL
  value: "info"  # debug, info, warn, error
- name: LOG_FORMAT
  value: "json"  # json, console
- name: LOG_CALLER
  value: "true"
- name: LOG_STACKTRACE_LEVEL
  value: "error"

Structured Logging¶

Configure structured logging format:

data:
  config.yaml: |
    logging:
      level: "info"
      format: "json"
      caller: true
      stacktraceLevel: "error"
      fields:
        service: "git-change-operator"
        version: "v1.0.0"
      outputs:
        - "stdout"
        - "/var/log/git-change-operator.log"

Security Configuration¶

Pod Security Standards¶

Configure Pod Security Standards:

# Namespace configuration
apiVersion: v1
kind: Namespace
metadata:
  name: git-change-operator-system
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted

Security Context¶

Configure security context for the controller:

# config/manager/manager.yaml
spec:
  template:
    spec:
      securityContext:
        runAsNonRoot: true
        runAsUser: 65532
        runAsGroup: 65532
        fsGroup: 65532
        seccompProfile:
          type: RuntimeDefault
      containers:
      - name: manager
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
          readOnlyRootFilesystem: true
          runAsNonRoot: true
          runAsUser: 65532
          runAsGroup: 65532

Network Policies¶

Restrict network access:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: git-change-operator-netpol
  namespace: git-change-operator-system
spec:
  podSelector:
    matchLabels:
      control-plane: controller-manager
  policyTypes:
  - Ingress
  - Egress
  ingress:
  - from:
    - namespaceSelector:
        matchLabels:
          name: git-change-operator-system
    ports:
    - protocol: TCP
      port: 8080  # metrics
    - protocol: TCP
      port: 9443  # webhooks
  egress:
  - {}  # Allow all egress (for Git operations)

Environment-Specific Configuration¶

Development Environment¶

# dev/config.yaml
git:
  timeout: "60s"
  defaultBranch: "dev"

reconciliation:
  interval: "10s"  # Faster reconciliation for development
  maxConcurrent: 5

logging:
  level: "debug"
  format: "console"

features:
  enableMetrics: true
  enableProfiling: true  # Enable profiling in dev
  enableTracing: true

Production Environment¶

# prod/config.yaml
git:
  timeout: "300s"
  defaultBranch: "main"

reconciliation:
  interval: "60s"  # Slower reconciliation for stability
  maxConcurrent: 20

logging:
  level: "info"
  format: "json"

features:
  enableMetrics: true
  enableProfiling: false  # Disable profiling in production
  enableTracing: false

security:
  enableWebhooks: true
  requireTLS: true
  minTLSVersion: "1.2"

Enterprise Environment¶

# enterprise/config.yaml
git:
  timeout: "600s"
  defaultBranch: "main"
  proxy:
    http: "http://proxy.company.com:8080"
    https: "http://proxy.company.com:8080"
    noProxy: "localhost,127.0.0.1,.company.com"

reconciliation:
  interval: "300s"  # Conservative reconciliation
  maxConcurrent: 50

logging:
  level: "info"
  format: "json"
  auditLog:
    enabled: true
    path: "/var/log/audit/git-change-operator.log"

security:
  enableWebhooks: true
  requireTLS: true
  minTLSVersion: "1.3"
  certificateAuthority: "/etc/ssl/certs/ca-certificates.crt"

compliance:
  enableAuditLogging: true
  retentionPeriod: "2555d"  # 7 years
  encryptionAtRest: true

Configuration Validation¶

Webhook Validation¶

The operator includes admission webhooks to validate configurations:

# Automatic validation for GitCommit resources
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionWebhook
metadata:
  name: vgitcommit.kb.io
webhooks:
- name: vgitcommit.kb.io
  clientConfig:
    service:
      name: webhook-service
      namespace: git-change-operator-system
      path: /validate-git-galos-one-v1-gitcommit
  rules:
  - operations: ["CREATE", "UPDATE"]
    apiGroups: ["gco.galos.one"]
    apiVersions: ["v1"]
    resources: ["gitcommits"]

Configuration Testing¶

Test your configuration before applying:

# Validate GitCommit resource
kubectl apply --dry-run=server -f gitcommit.yaml

# Validate with webhook
kubectl apply --dry-run=server -f gitcommit.yaml --validate=true

# Test configuration parsing
git-change-operator --config=config.yaml --validate-config

Troubleshooting Configuration¶

Common Configuration Issues¶

Invalid Git Repository URLs¶

# ❌ Invalid
repository: "github.com/user/repo"

# ✅ Valid
repository: "https://github.com/user/repo.git"
repository: "[email protected]:user/repo.git"

Missing Required Fields¶

# ❌ Missing required fields
apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: incomplete
spec:
  repository: "https://github.com/user/repo.git"
  # Missing: branch, message

# ✅ Complete
apiVersion: gco.galos.one/v1
kind: GitCommit
metadata:
  name: complete
spec:
  repository: "https://github.com/user/repo.git"
  branch: "main"
  message: "Update configuration"

Resource Reference Errors¶

# ❌ Invalid field path
resourceRef:
  fieldPath: "data.nonexistent"

# ✅ Valid field path
resourceRef:
  fieldPath: "data.config"

Configuration Debugging¶

Enable debug logging to troubleshoot configuration issues:

# Enable debug logging
kubectl patch deployment git-change-operator-controller-manager \
  -n git-change-operator-system \
  --type='json' \
  -p='[{"op": "replace", "path": "/spec/template/spec/containers/0/env/0/value", "value": "debug"}]'

# View debug logs
kubectl logs -n git-change-operator-system -l control-plane=controller-manager --tail=100 -f

Next Steps¶

After configuring the operator:

GitCommit Resources - Learn about GitCommit resources
PullRequest Resources - Understand PullRequest automation
Authentication - Set up secure authentication
Examples - See real-world configuration examples

For advanced configuration scenarios, see our Enterprise Setup Guide.