Skip to main content
logoTetrate Patch ServiceVersion: alpha

Your Repository's Files

Every repository that receives managed upgrades has the same few files, whether you connected it or Tetrate provisioned it. This page shows each one and how to read it. You rarely edit them by hand: the console generates them, and upgrades keep them current.

The Layout​

Everything Patch Service reads lives under .tetrate/, with one directory per product and one envs/<environment>/ directory per environment. A repository starts with a single environment called default.

.tetrate/
├── patch-service.yaml          the manifest
├── README.md                   a short description of this directory
├── patch-service-agent/        the agent
│   ├── values-customer.yaml    the agent's settings
│   └── envs/default/
│       └── values-versions.yaml
└── teg/                        one directory per product
    └── envs/default/
        └── values-versions.yaml
.github/workflows/tetrate-upgrades.yaml   the upgrade workflow

The agent is laid out like a product, so its upgrades arrive the same way. Depending on how you deploy, a few more files sit next to these: an Argo CD Application, a Flux HelmRelease, or a Terraform module for the agent, for example. The pages for Argo CD, Flux and Terraform cover them.

The Manifest​

.tetrate/patch-service.yaml tells Patch Service and the upgrade workflow what the repository deploys. Here is one for an Argo CD repository that deploys Tetrate Enterprise Gateway (TEG):

version: 1
customer: acme
products:
  agent:
    chart:
      component: patch-service-agent
      file: .tetrate/patch-service-agent/envs/{environment}/application.yaml
      paths:
        - '.spec.sources[0].targetRevision'
    environments:
      default:
        versions: .tetrate/patch-service-agent/envs/default/values-versions.yaml
  teg:
    environments:
      default:
        versions: .tetrate/teg/envs/default/values-versions.yaml
        chart:
          component: teg-control-plane
          file: clusters/prod/apps/teg.yaml
          paths:
            - '.spec.sources[0].targetRevision'
FieldWhat it means
customerYour Patch Service account. This is how Patch Service knows the repository is yours: only someone who can push to it can write this line.
productsThe products the repository deploys. agent is always there.
environments.<name>.versionsThe versions file of that environment.
chartWhere the product's chart version is written, so upgrades can move it too: the file, and the paths of the fields holding the version in it. {environment} in file stands for each environment's name. component is the Tetrate release the chart follows. Without a chart entry, upgrades move only the images.

The file the console generates also carries commented-out examples of more environments.

Versions Files​

A versions file pins the exact images one environment runs. Your deploy tool passes it to the product's Helm chart as a values file, listed after your own values files so its pins win. The chart reads it like any other values file.

It has two parts. The first, under images:, is the pins. Upgrades rewrite this part and nothing else:

images:
  teg-control-plane:
    release-version: "1.9.3"
    variant: teg
    repository: &teg-control-plane-repository docker.io/tetrate/teg-envoy-gateway
    tag: &teg-control-plane-tag "v1.9.3"
    ref: &teg-control-plane-ref docker.io/tetrate/teg-envoy-gateway:v1.9.3
FieldWhat it means
release-versionThe Tetrate release this image comes from. The workflow compares it with the latest release.
variantThe build of the image to follow, such as distroless or fips. An image without a variant is never upgraded.
repository, tag, refThe image itself, written three ways: its repository, its tag, and both together.

The second part, below the pins, tells the chart where to use each image. It is written in the chart's own values keys:

deployment:
  tegEnvoyGateway:
    image:
      repository: *teg-control-plane-repository
      tag: *teg-control-plane-tag

The & and * are standard YAML. &teg-control-plane-tag names a value, and *teg-control-plane-tag reuses it. So the chart's deployment.tegEnvoyGateway.image.tag is always whatever the pin's tag says. When an upgrade changes a pin, every place that uses it follows. Some chart keys take the repository and tag separately and others the whole reference, which is why each pin has all three.

You never need to edit either part to receive upgrades. The second part changes only if you want an image used somewhere new.

Your Own Settings​

Keep your own configuration for the product, such as resources, replicas or gateway settings, where it is today: in your own values files, listed before the versions file. Nothing Patch Service does ever changes them.

Where the Chart Version Lives​

A chart version is not in the versions file. It stays where your deploy tool reads it, and the manifest's chart entry points at it. The upgrade moves it in the same pull request as the images:

Deploy toolWhere the chart version is
Argo CDThe Application's targetRevision
FluxThe HelmRelease's spec.chart.spec.version, or the OCIRepository's tag
Terraformchart-version.json, next to the versions file, which your helm_release reads

Adding an Environment​

Each environment gets its own versions file, so that it can be upgraded on its own:

  1. Copy envs/default/ to envs/<environment>/, for example envs/prod/.
  2. Add the environment to the product in the manifest, as the commented example there shows.
  3. Point that environment's deploy file at the new versions file, and set its patch.tetrate.io/environment label to the new name.

From then on, each environment receives its own upgrade pull requests.

Holding an Upgrade Back​

  • One request: leave it unmerged, or close it. A closed request is opened again at the next run if the upgrade is still pending.
  • One image: remove its variant in the versions file. The image is then never upgraded in that environment, until you put the variant back.
  • One environment's chart: add chart: {hold: true} to the environment in the manifest. Its images still upgrade.

Next Steps​