Image Update Automations

apiVersion: image.toolkit.fluxcd.io/v1beta1

// ImageUpdateAutomationSpec defines the desired state of ImageUpdateAutomation
type ImageUpdateAutomationSpec struct {
	// SourceRef refers to the resource giving access details
	// to a git repository.
	// +required
	SourceRef CrossNamespaceSourceReference `json:"sourceRef"`
	// GitSpec contains all the git-specific definitions. This is
	// technically optional, but in practice mandatory until there are
	// other kinds of source allowed.
	// +optional
	GitSpec *GitSpec `json:"git,omitempty"`

	// Interval gives an lower bound for how often the automation
	// run should be attempted.
	// +required
	Interval metav1.Duration `json:"interval"`

	// Update gives the specification for how to update the files in
	// the repository. This can be left empty, to use the default
	// value.
	// +kubebuilder:default={"strategy":"Setters"}
	Update *UpdateStrategy `json:"update,omitempty"`

	// Suspend tells the controller to not run this automation, until
	// it is unset (or set to false). Defaults to false.
	// +optional
	Suspend bool `json:"suspend,omitempty"`
}

// CrossNamespaceSourceReference contains enough information to let you locate the
// typed Kubernetes resource object at cluster level.
type CrossNamespaceSourceReference struct {
	// API version of the referent.
	// +optional
	APIVersion string `json:"apiVersion,omitempty"`

	// Kind of the referent.
	// +kubebuilder:validation:Enum=GitRepository
	// +kubebuilder:default=GitRepository
	// +required
	Kind string `json:"kind"`

	// Name of the referent.
	// +required
	Name string `json:"name"`

	// Namespace of the referent, defaults to the namespace of the Kubernetes resource object that contains the reference.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
metadata:
  name: webapp
  namespace: apps
spec:
  interval: 5m
  sourceRef:
    kind: GitRepository # the only valid value, but good practice to be explicit here
    name: apps
    namespace: flux-system

type GitSpec struct {
	// Checkout gives the parameters for cloning the git repository,
	// ready to make changes. If not present, the `spec.ref` field from the
	// referenced `GitRepository` or its default will be used.
	// +optional
	Checkout *GitCheckoutSpec `json:"checkout,omitempty"`

	// Commit specifies how to commit to the git repository.
	// +required
	Commit CommitSpec `json:"commit"`

	// Push specifies how and where to push commits made by the
	// automation. If missing, commits are pushed (back) to
	// `.spec.checkout.branch` or its default.
	// +optional
	Push *PushSpec `json:"push,omitempty"`
}

type GitCheckoutSpec struct {
	// Reference gives a branch, tag or commit to clone from the Git
	// repository.
	// +required
	Reference sourcev1.GitRepositoryRef `json:"ref"`
}

// CommitSpec specifies how to commit changes to the git repository
type CommitSpec struct {
	// Author gives the email and optionally the name to use as the
	// author of commits.
	// +required
	Author CommitUser `json:"author"`
	// SigningKey provides the option to sign commits with a GPG key
	// +optional
	SigningKey *SigningKey `json:"signingKey,omitempty"`
	// MessageTemplate provides a template for the commit message,
	// into which will be interpolated the details of the change made.
	// +optional
	MessageTemplate string `json:"messageTemplate,omitempty"`
}

type CommitUser struct {
	// Name gives the name to provide when making a commit.
	// +optional
	Name string `json:"name,omitempty"`
	// Email gives the email to provide when making a commit.
	// +required
	Email string `json:"email"`
}

// SigningKey references a Kubernetes secret that contains a GPG keypair
type SigningKey struct {
	// SecretRef holds the name to a secret that contains a 'git.asc' key
	// corresponding to the ASCII Armored file containing the GPG signing
	// keypair as the value. It must be in the same namespace as the
	// ImageUpdateAutomation.
	// +required
	SecretRef meta.LocalObjectReference `json:"secretRef,omitempty"`
}

spec:
  git:
    commit:
      author:
        name: Fluxbot
        email: flux@example.com

---
apiVersion: v1
kind: Secret
metadata:
  name: signing-key
  namespace: default
stringData:
  git.asc: |
    <ARMOR ENCODED PGP KEY>    
  passphrase: <private-key-passphrase>

spec:
  git:
    commit:
      messageTemplate: |
        Automated image update by Flux
        
        [ci skip]        

// internal/controller/imageupdateautomation_controller.go

// TemplateData is the type of the value given to the commit message
// template.
type TemplateData struct {
	AutomationObject struct {
      Name, Namespace string
    }
	Updated          update.Result
}

// pkg/update/result.go

// ImageRef represents the image reference used to replace a field
// value in an update.
type ImageRef interface {
	// String returns a string representation of the image ref as it
	// is used in the update; e.g., "helloworld:v1.0.1"
	String() string
	// Identifier returns the tag or digest; e.g., "v1.0.1"
	Identifier() string
	// Repository returns the repository component of the ImageRef,
	// with an implied defaults, e.g., "library/helloworld"
	Repository() string
	// Registry returns the registry component of the ImageRef, e.g.,
	// "index.docker.io"
	Registry() string
	// Name gives the fully-qualified reference name, e.g.,
	// "index.docker.io/library/helloworld:v1.0.1"
	Name() string
}

// ObjectIdentifier holds the identifying data for a particular
// object. This won't always have a name (e.g., a kustomization.yaml).
type ObjectIdentifier struct {
	Name, Namespace, APIVersion, Kind string
}

// Result reports the outcome of an automated update. It has a nested
// structure file->objects->images. Different projections (e.g., all
// the images, regardless of object) are available via methods.
type Result struct {
	Files map[string]FileResult
}

// FileResult gives the updates in a particular file.
type FileResult struct {
	Objects map[ObjectIdentifier][]ImageRef
}

// Images returns all the images that were involved in at least one
// update.
func (r Result) Images() []ImageRef {
    // ...
}

// Objects returns a map of all the objects against the images updated
// within, regardless of which file they appear in.
func (r Result) Objects() map[ObjectIdentifier][]ImageRef {
    // ...
}

spec:
  commit:
    messageTemplate: |
      Automated image update
      
      Automation name: {{ .AutomationObject }}
      
      Files:
      {{ range $filename, $_ := .Updated.Files -}}
      - {{ $filename }}
      {{ end -}}
      
      Objects:
      {{ range $resource, $_ := .Updated.Objects -}}
      - {{ $resource.Kind }} {{ $resource.Name }}
      {{ end -}}
      
      Images:
      {{ range .Updated.Images -}}
      - {{.}}
      {{ end -}}      

kind: ImageUpdateAutomation
metadata:
  name: flux-system
spec:
  git:
    commit:
      messageTemplate: |
        Automated image update

        Automation name: {{ .AutomationObject }}

        Files:
        {{ range $filename, $_ := .Updated.Files -}}
        - {{ $filename }}
        {{ end -}}

        Objects:
        {{ range $resource, $_ := .Updated.Objects -}}
        - {{ $resource.Kind | lower }} {{ $resource.Name | lower  }}
        {{ end -}}

        Images:
        {{ range $image, $_ := .Updated.Images -}}
        	{{ if contains "1.0.0" $image -}}
        		- {{ $image }}
        	{{ else -}}
        		[skip ci] wrong image
        	{{ end -}}        
        {{ end -}}                
      author:
        email: fluxcdbot@users.noreply.github.com
        name: fluxcdbot

// PushSpec specifies how and where to push commits.
type PushSpec struct {
	// Branch specifies that commits should be pushed to the branch
	// named. The branch is created using `.spec.checkout.branch` as the
	// starting point, if it doesn't already exist.
	// +optional
	Branch string `json:"branch,omitempty"`

	// Refspec specifies the Git Refspec to use for a push operation.
	// If both Branch and Refspec are provided, then the commit is pushed
	// to the branch and also using the specified refspec.
	// For more details about Git Refspecs, see:
	// https://git-scm.com/book/en/v2/Git-Internals-The-Refspec
	// +optional
	Refspec string `json:"refspec,omitempty"`

	// Options specifies the push options that are sent to the Git
	// server when performing a push operation. For details, see:
	// https://git-scm.com/docs/git-push#Documentation/git-push.txt---push-optionltoptiongt
	Options map[string]string `json:"options,omitempty"`
}

spec:
  git:
    checkout:
      ref:
        branch: main
    push:
      branch: auto

spec:
  git:
    checkout:
      ref:
        branch: main
    push:
      refspec: refs/heads/main:refs/heads/auto

spec:
  git:
    push:
      branch: dev
      options:
        merge_request.create: ""
        merge_request.target: release

spec:
  git:
    checkout:
      ref:
        branch: main
    commit:
      author:
        email: flux@localdomain
        name: flux
      messageTemplate: |
        Perform automatic image update

        Automation name: {{ .AutomationObject }}

        Files:
        {{ range $filename, $_ := .Updated.Files -}}
        - {{ $filename }}
        {{ end }}
        Objects:
        {{ range $resource, $_ := .Updated.Objects -}}
        - {{ $resource.Kind }} {{ $resource.Name }}
        {{ end }}
        Images:
        {{ range .Updated.Images -}}
        - {{ . }}
        {{ end }}
        {{- $ChangeId := .AutomationObject -}}
        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Files | toString ) -}}
        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Objects | toString ) -}}
        {{- $ChangeId = printf "%s%s" $ChangeId ( .Updated.Images | toString ) }}
        Change-Id: {{ printf "I%s" ( sha256sum $ChangeId | trunc 40 ) }}        
    push:
      branch: auto
      refspec: refs/heads/auto:refs/heads/main

// UpdateStrategyName is the type for names that go in
// .update.strategy. NB the value in the const immediately below.
// +kubebuilder:validation:Enum=Setters
type UpdateStrategyName string

const (
	// UpdateStrategySetters is the name of the update strategy that
	// uses kyaml setters. NB the value in the enum annotation for the
	// type, above.
	UpdateStrategySetters UpdateStrategyName = "Setters"
)

// UpdateStrategy is a union of the various strategies for updating
// the Git repository. Parameters for each strategy (if any) can be
// inlined here.
type UpdateStrategy struct {
	// Strategy names the strategy to be used.
	// +required
	// +kubebuilder:default=Setters
	Strategy UpdateStrategyName `json:"strategy"`

	// Path to the directory containing the manifests to be updated.
	// Defaults to 'None', which translates to the root path
	// of the GitRepositoryRef.
	// +optional
	Path string `json:"path,omitempty"`
}

// ImageUpdateAutomationStatus defines the observed state of ImageUpdateAutomation
type ImageUpdateAutomationStatus struct {
	// LastAutomationRunTime records the last time the controller ran
	// this automation through to completion (even if no updates were
	// made).
	// +optional
	LastAutomationRunTime *metav1.Time `json:"lastAutomationRunTime,omitempty"`
	// LastPushCommit records the SHA1 of the last commit made by the
	// controller, for this automation object
	// +optional
	LastPushCommit string `json:"lastPushCommit,omitempty"`
	// LastPushTime records the time of the last pushed change.
	// +optional
	LastPushTime *metav1.Time `json:"lastPushTime,omitempty"`
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
	// +optional
	Conditions                  []metav1.Condition `json:"conditions,omitempty"`
	meta.ReconcileRequestStatus `json:",inline"`
}

apiVersion: image.toolkit.fluxcd.io/v1alpha1
kind: ImageUpdateAutomation
spec:
  checkout:
    gitRepositoryRef:
      name: auto-repo
    branch: main
  interval: 5m
  # omit suspend, which has not changed
  update:
    strategy: Setters
    path: ./app
  commit:
    authorName: fluxbot
    authorEmail: fluxbot@example.com
    messageTemplate: |
      An automated update from FluxBot
      [ci skip]      
    signingKey:
      secretRef:
        name: git-pgp
  push:
    branch: auto

apiVersion: image.toolkit.fluxcd.io/v1alpha1

# becomes

apiVersion: image.toolkit.fluxcd.io/v1beta1

spec:
  checkout:
    gitRepositoryRef:
      name: auto-repo
    branch:
      main

# becomes

spec:
  sourceRef:
    kind: GitRepository # the default, but good practice to be explicit here
    name: auto-repo
  git:
    checkout:
      ref:
        branch: main

spec:
  commit:
    authorName: fluxbot
    authorEmail: fluxbot@example.com
    messageTemplate: |
      An automated update from FluxBot
      [ci skip]      
    signingKey:
      secretRef:
        name: git-pgp

# becomes

spec:
  git:
    commit:
      author:
        name: fluxbot
        email: fluxbot@example.com
      messageTemplate: |
        An automated update from FluxBot
        [ci skip]        
      signingKey:
        secretRef:
          name: git-pgp

spec:
  push:
    branch: auto

# becomes

spec:
  git:
    push:
      branch: auto

apiVersion: image.toolkit.fluxcd.io/v1beta1
kind: ImageUpdateAutomation
spec:
  sourceRef: # moved from `.spec.checkout`
    kind: GitRepository
    name: auto-repo
  interval: 5m
  # omit suspend, which has not changed
  update:
    strategy: Setters
    path: ./app
  git:
    checkout: # moved under `git`, loses `gitRepositoryRef`
      ref:
        branch: main # moved into `ref` struct
    commit: # moved under `git`
      author:
        name: fluxbot  # moved from `authorName`
        email: fluxbot@example.com # moved from `authorEmail`
      messageTemplate: |
        An automated update from FluxBot
        [ci skip]        
      signingKey:
        secretRef:
          name: git-pgp
    push: # moved under `git`
      branch: auto