tanzu-source-controller

The controller follows the spirit of the FluxCD Source Controller. An ImageRepository resource is able to resolve source from the content of an image in an image registry.

Pre-requisites
Install
- Releases
- From Source
Developer Setup
Troubleshooting
Reference Documentation
- ImageRepository
- MavenArtifact
License

Pre-requisites

We require Golang 1.20+ to build the controller and deploy it. Internally, the make target will create a local version of ko to build the controller, and kapp to deploy the controller to a cluster.

All 3 CLIs can be easily installed via brew:

brew tap vmware-tanzu/carvel && brew install imgpkg kbld kapp

This project requires access to a container registry for fetching image metadata. Therefore, it will not work for images that have bypassed a registry by loading directly into a local daemon.

Finally requires installing cert-manager.

Install

Releases

Built release bundles are available with step by step install instructions, or you can build directly from source.

From Source

Install cert-manager:

kapp deploy -a cert-manager -f https://github.com/jetstack/cert-manager/releases/download/v1.8.0/cert-manager.yaml

Optional: Trust additional certificate authorities certificate

If a ImageRepository resource references an image in a registry whose certificate was not signed by a Public Certificate Authority (CA), a certificate error x509: certificate signed by unknown authority will occur while applying conventions. To trust additional certificate authorities include the PEM encoded CA certificates in a file and set following environment variable to the location of that file.
```
CA_DATA=path/to/certfile # a PEM-encoded CA certificate
```

Build and install Source Controller:

kapp deploy -a source-controller \
  -f <( \
    ko resolve -f <( \
      ytt \
        -f dist/source-controller.yaml \
        -f dist/package-overlay.yaml \
        --data-value-file ca_cert_data=${CA_DATA:-dist/ca.pem} \
      ) \
  )

Note: you'll need to export KO_DOCKER_REPO=${ACCESSIBLE_DOCKER_REPO} such that ko can push to the repository and your cluster can pull from it. Visit the ko README for more information.

To uninstall Source Controller:

kapp delete -a source-conntroller

Reference Documentation

ImageRepository

---
apiVersion: source.apps.tanzu.vmware.com/v1alpha1
kind: ImageRepository
metadata:
  name: imagerepository-sample
spec:
  image: registry.example/image/repository:tag
  # optional fields
  interval: 5m
  imagePullSecrets: []
  serviceAccountName: default

ImageRepository resolves source code defined in an OCI image repository, exposing the resulting source artifact at a URL defined by .status.artifact.url.

The interval determines how often to check tagged images for changes. Setting this value too high will result in delays discovering new sources, while setting it to low may trigger a registry's rate limits.

Repository credentials may be defined as image pull secrets either referenced directly from the resources at .spec.imagePullSecrets, or attached to a service account referenced at .spec.serviceAccountName. The default service account name "default" is used if not otherwise specified. The default credential helpers for the registry are also used, for example, pulling from GCR on a GKE cluster.

MavenArtifact

---
apiVersion: source.apps.tanzu.vmware.com/v1alpha1
kind: MavenArtifact
metadata:
  name: mavenartifact-sample
spec:
  artifact:
    groupId: org.springframework.boot
    artifactId: spring-boot
    version: "2.7.0"
  repository:
    url: https://repo1.maven.org/maven2
  interval: 5m0s
  timeout: 1m0s

MavenArtifact resolves artifact from a Maven repository, exposing the resulting artifact at a URL defined by .status.artifact.url.

The interval determines how often to check artifact for changes. Setting this value too high will result in delays in discovering new sources, while setting it too low may trigger a repository's rate limits.

Repository credentials may be defined as secrets referenced from the resources at .spec.repository.secretRef. Secret referenced by spec.repository.secretRef is parsed as following:

---
apiVersion: v1
kind: Secret
metadata:
  name: auth-secret
type: Opaque
data:
  username: <BASE64>
  password: <BASE64>
  caFile:   <BASE64>   // PEM Encoded certificate data for Custom CA 
  certFile: <BASE64>   // PEM-encoded client certificate
  keyFile:  <BASE64>   // Private Key

Maven supports a broad set of version syntax. Source Controller supports a strict subset of Maven's version syntax in order to ensure compatibility and avoid user confusion. The subset of supported syntax may grow over time, but will never expand past the syntax defined directly by Maven. This behavior means that we can use mvn as a reference implementation for artifact resolution.

Version support implemented in the following order:

pinned version - an exact match of a version in maven-metadata.xml (versioning/versions/version)
RELEASE - metaversion defined in maven-metadata.xml (versioning/release)
*-SNAPSHOT - the newest artifact for a snapshot version
LATEST - metaversion defined in maven-metadata.xml (versioning/latest)
version ranges - https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html

NOTE: Pinned versions should be immutable, all other versions are dynamic and may change at any time. The .spec.interval defines how frequently to check for updated artifacts.

Troubleshooting

For basic troubleshooting, please see the troubleshooting guide here.

Developer Setup

For Source Controller development setup, please see the development guide here

Contributing

The tanzu-source-controller project team welcomes contributions from the community. Before you start working with tanzu-source-controller, please read and sign our Contributor License Agreement(https://cla.vmware.com/cla/1/preview). If you wish to contribute code and you have not signed our contributor license agreement (CLA), our bot will prompt you to do so when you open a Pull Request. For any questions about the CLA process, please refer to our FAQ.

vmware-tanzu / tanzu-source-controller

readme