Update policy Feedback

[olblak]

I starting this discussion to gather all ideas around Updatecli policy and to identify missing steps for moving the feature out of experimental

Context

The updatecli policy feature, provides the ability to publish any Updatecli to an registry and then to reuse them either with command line or via the update-compose.yaml such as on the updatelci/website

examples:

• updatecli compose diff -f update-compose.yaml --experimental
• updatecli diff ghcr.io/updatecli/policies/nodejs/netlify:0.3.0
• updatecli diff ghcr.io/updatecli/policies/nodejs/netlify:0.3.0@sha256:41c2af6a10da1f4b4b91717ebaa4659332dd3d7107919c494c71f1f618aeaad8

The goal is to be more DRY but not having to copy/paste the same policy over and over to multiple git repository.

[mcwarman]

I've been using within in a organisation where I manage multiple terraform repos.

Policy releases

For releasing the policies I went down a slightly different approach to updatecli/policies, relying on GitHub workflows to do the lifting as oppose to shell scripts. I also added tagging and releases similar to how a helm chart repo works: name-version.

GitHub Workflow

name: Policy Release

on:
  push:
    branches:
      - main
    paths:
      - "updatecli/policies/**"

defaults:
  run:
    shell: bash

permissions: {}

jobs:
  changed-policies:
    name: Get changed policies
    runs-on: ubuntu-latest
    permissions:
      contents: read
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v41
        with:
          json: true
          quotepath: false
          files: "updatecli/policies/**/policy.yaml"
          dir_names: true

      - name: Set changed files as output
        id: set-matrix
        run: |
          matrix="{\"directory\":${{ steps.changed-files.outputs.all_changed_files }}}"
          echo "$matrix" | jq .
          echo "matrix=$matrix" >> "$GITHUB_OUTPUT"

  release:
    name: Release
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    needs:
      - changed-policies
    strategy:
      matrix: ${{ fromJSON(needs.changed-policies.outputs.matrix) }}
      fail-fast: false
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup updatecli
        uses: updatecli/updatecli-action@v2

      - name: Log in to the container registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Set policy details
        id: policy
        env:
          POLICY_DIR: ${{ matrix.directory }}
        run: |
          name=$(realpath --relative-to=./updatecli/policies "${POLICY_DIR}")
          version=$(yq .version "${POLICY_DIR}/policy.yaml")
          {
            printf "name=$name\n"
            printf "version=$version\n"
            printf "release=$name-$version\n"
          } >>"${GITHUB_OUTPUT}"

      - name: Create github release
        id: github-release
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE: ${{ steps.policy.outputs.release }}
        run: |
          git tag "${RELEASE}"
          git push origin "${RELEASE}"
          gh release create "${RELEASE}" --verify-tag --latest

      - name: Push updatecli manifest
        working-directory: ${{ matrix.directory }}
        env:
          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
          POLICY_NAME: ${{ steps.policy.outputs.name }}
        run: |
          updatecli manifest push \
            --config updatecli.d \
            --policy policy.yaml \
            --values values.yaml \
            --tag "ghcr.io/${GITHUB_REPOSITORY_OWNER}/${GITHUB_REPOSITORY_NAME}/${POLICY_NAME}" \
            .

This is more a preference thing, but I thought i'd share the different approach.

I do think providing a standard approach (possibly a template/documentation similar to scoop bucket (Creating your own bucket) and brew tap (How to Create and Maintain a Tap)) for policy repository bootstrapping would be helpful.

Policy.yaml vs policy.yaml

Also for whatever reason I wasn't a fan Policy.yaml and have been using policy.yaml as it didn't make sense to me why the case had to be different, with most other things being lower, again its preference thing, but knowing the driver behind the decision might win me over. I had no issues with using a different approach.

latest tag

It wasn't clear to me that the latest tag was magic and I was using oras tag to create a latest tag. I only realised after debugging something, it turns out it was in the documentation and I just missed it (didn't read it). But its just worth mentioning it did throw me for a bit.

It even logs it as being ignored, but my brain didn't put two and two together for a while:

updatecli/pkg/core/registry/utils.go

Line 45 in 794acb9

logrus.Warningf("Ignoring tag %q - %q", tags[i], err)

Possibly two enhancement options here:

• If latest is in the repo use it.
• If latest is in the repo the warning is clearer to the user that its not being used.

WARN: Ignoring tag latest ...
WARN: NOTE: When tag latest is used, updatecli will pull the lastest semantic version, and not use the latest tag.

[olblak]

Wow that's a lot of feedback

For releasing the policies I went down a slightly different approach to updatecli/policies

The way you release is really interesting and probably better than what I am currently doing. I'll give a try on a new org

Policy.yaml vs policy.yaml

I agree it's a matter of taste, I wanted to highlight its importance by using a capital letter and reducing the risk of jsonschema store collision with another file
https://github.com/SchemaStore/schemastore/blob/5b21d70133bf90a18d69ea84b60634fb0da07292/src/api/json/catalog.json#L5319

So if you have a file name "Policy.yaml" with a parent directory "updatecli" then IDE will validate the syntax similarly to Updatecli manifests

I do think providing a standard approach

This a great feedback and I wondered if I needed it, but now you confirm that yes :)
I'll add one

[olblak]

I do think providing a standard approach (possibly a template/documentation similar to scoop bucket (Creating your own bucket) and brew tap (How to Create and Maintain a Tap)) for policy repository bootstrapping would be helpful.

I open this pullrequest which adds a new command updatecli manifest init
to bootstrap a new policy with the following files

.
├── Policy.yaml
├── README.md
├── default.yaml
├── updatecli.d
│  └── default.yaml
└── values.d
   └── default.yaml`

[olblak]

I opened a pullrequest to move shareable policies out of experimental as it's working great on my projects and I don't envision any breaking changes.
#1973