Skip to content

Repository Custom Resource

Jump to bottom
Gary Vermeulen edited this page Nov 28, 2025 · 6 revisions

Repository Custom Resource

This section contains more contextual information about the Repository Custom Resource.

API Docs

These API Docs are autogenerated using Layer7 Operator's CRDs using crdoc

Index

This section is complimentary to the API Docs above providing a comprehensive view of configuration options.

Overview

The Repository Controller reconciles external Git repositories (or bundles that can be downloaded via HTTP; e.g. like might be stored in a solution like Artifactory) with the Layer7 Operator. The Repository Controller is responsible for ensuring that the latest commit is always available to be applied to Gateways via repository references. Repositories must contain valid graphman bundles in json format.

Limitations for Static Repositories

The Repository Controller compresses downloaded repositories and stores them as Kubernetes Secrets. These secrets are then mounted to the graphman-static-init container and bootstrapped to the container gateway before it starts.

  • If a compressed repository is greater than 1mb in size (compressed)
    • A Kubernetes secret will not be created
      • Credentials will be passed to the graphman-static-init container and it will attempt to clone the repository and bootstrap the contents to the container gateway before it starts
        • Every Gateway Pod will do this creating a direct dependency on the Git repo
        • The graphman-static-init container only supports http authentication and git types.

Recommendation

  • If you have large policy repositories or need to load aars/jars/additional configuration use an initContainer to bootstrap the configuration to your Gateway. This is also the recommended approach for the Gateway Helm Chart, examples can be found here

Alternative

  • Gateway Repository References that are of type dynamic make use of an ephemeral filesystem and do not have size limitations.

Back to Index

Repository Types

Git Repository

Git repositories are the most common type of repository used with the Layer7 Operator. They support branches, tags, and various authentication methods.

Config - Read more here

Using a Branch

Here is a simple representation of how to configure this Repository that is hosted on github.com

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  remoteName: origin
  auth: {}

Note

This config references the main branch. This means that whenever that branch is updated the repository will be reconciled. In production environments we recommend using tags/releases which are static, this avoids unintentional updates that may have unintended consequences.

Using a Tag

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  tag: 1.0.0
  remoteName: origin
  auth: {}

Note

  • Tags do not change, once cloned this will not be checked for updates
  • If both branch and tag are specified, branch will take precedence and tag will be ignored
  • If both branch and tag are missing, the entire repository will be cloned
  • remoteName defaults to "origin" if not specified

Back to Index

HTTP Repository

HTTP repositories allow you to download bundled configuration from HTTP endpoints, such as Artifactory or other file servers.

Config - Read more here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: file-repository
spec:
  type: http
  enabled: true
  endpoint: https://myfileserver/implodedbundle.tar.gz 
  auth: {}

Note

  • HTTP repositories support basic authentication
  • The endpoint should point to a compressed bundle (e.g., .tar.gz)
  • The commit status will be a sha1sum of the http repository contents

Back to Index

Local Repository

Local repositories allow the Repository controller to use a local Kubernetes Secret as a repository source. This is useful for storing small bundles directly in Kubernetes.

Config - Read more here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: local-repository
spec:
  type: local
  enabled: true
  localReference:
    secretName: my-graphman-bundle-secret

Note

  • The referenced secret should contain valid graphman bundles
  • This is subject to the 1MB Kubernetes Secret size limit
  • Ideal for small configuration bundles

Back to Index

StateStore Repository

StateStore repositories retrieve configuration from a configured L7StateStore (typically Redis). This is useful for shared configuration across multiple clusters or environments.

Config - Read more here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: statestore-repository
spec:
  type: statestore
  enabled: true
  stateStoreReference: my-l7-statestore
  stateStoreKey: my-repository-key

Note

  • Requires an L7StateStore Custom Resource to be configured
  • stateStoreReference specifies which L7StateStore connection should be used
  • stateStoreKey specifies where the repository is stored in the state store
  • If type is statestore, this reference will read everything from the state store

Back to Index

Authentication

There are multiple authentication types available depending on the repository type.

Config - Read more here

Basic Authentication

Basic authentication is available for both Git and HTTP repositories. Credentials can be provided directly in the repository custom resource, but we recommend using an existing Kubernetes Secret.

Creating the Secret

The secret should contain the following keys:

USERNAME
TOKEN

An example can be found here

Git Repository with Basic Auth

A more detailed example can be found here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth:
    type: basic
    vendor: Github
    existingSecretName: repo-secret

Using Inline Credentials (Not Recommended)

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth:
    type: basic
    username: pat
    token: pat_token
    vendor: Github

HTTP Repository with Basic Auth

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: file-repository
spec:
  type: http
  enabled: true
  endpoint: https://myfileserver/implodedbundle.tar.gz 
  auth:
    type: basic
    username: username
    token: token
    existingSecretName: repo-secret

Note

  • vendor field is optional but helps identify the Git provider (github, gitlab, bitbucket, azure)
  • password or token are both acceptable fields
  • Always prefer using existingSecretName over inline credentials
  • If your git provider does not have a trusted CA signed certificate you can append -insecure to vendor
apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  enabled: true
  ..
  type: git
  auth:
    type: basic
    vendor: <vendor>-insecure
    ..

Back to Index

SSH Authentication

SSH Authentication is available for Git repositories and requires more configuration than Basic authentication.

This example provides more context on what to configure and how.

Creating the Secret

The secret should contain the following keys:

KNOWN_HOSTS
SSH_KEY
SSH_KEY_PASS (optional)

Using a Secret (Recommended)

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: ssh://git@github.com/username/reponame
  branch: main
  auth:
    type: ssh
    vendor: Github
    existingSecretName: ssh-repo-secret

Using Inline Configuration (Not Recommended)

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: ssh://git@yourgitserver.com/username/reponame
  branch: main
  auth:
    type: ssh
    sshKey: |+
      -----BEGIN OPENSSH PRIVATE KEY-----
      encrypted key value
      -----END OPENSSH PRIVATE KEY-----
    sshKeyPass: keypassphrase
    knownHosts: |+
      github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
      gitlab.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAfuCHKVTjquxvt6CM6tdG4SLp1Btn/nOeHHE5UOzRdf
      bitbucket.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIazEu89wgQZ4bqs3d63QSMzYVa0MuJ2e2gKTKqu+UUO

Note

  • SSH authentication is only supported for Git repositories
  • knownHosts is required for SSH authentication
  • sshKeyPass is optional if your SSH key is not password protected
  • Always prefer using existingSecretName over inline credentials

Back to Index

No Authentication

For public repositories or endpoints that don't require authentication, you can use an empty auth object.

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth:
    type: none

or simply:

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth: {}

Back to Index

Repository Sync Configuration

Configure how often the repository is checked for updates. This is particularly useful for branch-based repositories.

Config - Read more here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth: {}
  sync:
    interval: 300

Note

  • interval is specified in seconds
  • This configures how frequently the remote is checked for new commits
  • Tag-based repositories do not benefit from this as tags are immutable
  • Default sync interval applies if not specified

Back to Index

Labels and Annotations

Add custom labels and annotations to the Repository Custom Resource.

Config - Read more here

apiVersion: security.brcmlabs.com/v1
kind: Repository
metadata:
  name: l7-gw-myapis
spec:
  type: git
  enabled: true
  endpoint: https://github.com/Gazza7205/l7GWMyAPIs
  branch: main
  auth: {}
  labels:
    environment: production
    team: api-team
  annotations:
    description: "Production API configurations"

Back to Index

Encryption

Repositories may contain encrypted values such as this Gateway Secret in the sample framework repository.

The Repository Custom Resource does not need to contain the decryption passphrase, it is set in the Gateway. See Repository References here for more details.

Note

  • Encryption passphrases are configured at the Gateway level via repository references
  • This allows different Gateways to use different passphrases for the same repository
  • Encrypted values in repositories are decrypted when applied to the Gateway

Back to Index

Contents

Clone this wiki locally