Skip to main content

Package Installations

Packages provide a delivery method for installing and/or bootstrapping multiple clusters with software. Wayfinder uses packages to maintain its own package installations. Wayfinder administrators can also use packages as building blocks to install software in clusters in order to achieve standardisation, ensure company security policies, and save DevOps time.

Wayfinder automatically installs Flux on every workspace cluster, in the wf-manager namespace. During Wayfinder installation, Flux is preloaded with a number of HelmRepositories alongside the Wayfinder-maintained collection of charts. Flux helm-controller lets you declaratively manage helm chart releases, as described below.


Package Release Diagram


Workflow Overview​

Administrative / Configuration​

As a Wayfinder administrator, you can deploy applications across multiple clusters by creating packages and repositories in the management cluster. Both are globally scoped and apply to all workspaces with matching clusters.

  • A package is a reference to a specific version of a specific helm chart of a repository. A package contains the installation configuration which includes any secrets required for the installation.

  • A repository is a reference to a source of helm charts. A repository can be a source for multiple packages, but a package will only reference one repository. If a Package refers to a different repository (other than the ones preloaded with Flux), then you can add another Repository.

Both the package and the repository include selectors (matchLabels and/or matchExpressions) which, when matched to clusters, will cause the software to be installed on those clusters, whether it's an existing cluster, or a cluster that is being created. The package manifest example below shows the matchExpression selector, specifying that the package install applies to all AWS (i.e. EKS) clusters.


spec:
  selectors:
    matchExpressions:
      - key: appvia.io/provider
        operator: In
        values:
        - EKS

Internal to Wayfinder​

Package Definition Phase: A Package Release is automatically created for each cluster and additionally, a Repository Release is automatically created for each cluster that is matched by the repository selectors. The Package Release creates the relevant HelmRelease in the workspace cluster. The Repository Release creates the relevant HelmRepository in the workspace cluster.

Package Update Phase: When the package configuration is updated (i.e. the package version), Wayfinder creates a Package Update for each cluster that the package is installed on. Once the package update is approved (either manually or via auto-approval) the Package Release is triggered with the updated package installation configuration.


Kubernetes (Workspace Cluster)​

The Package Release and the Repository Release are pushed to the cluster where the package installation takes place via Flux.


Label matching​

A package is matched to a cluster via the selector field in the spec. This can contain matchLabels and/or matchExpressions depending on the use case. Once a cluster with matching labels or rule expression is found, a PackageRelease is created to track the installation of the software. A RepositoryRelease is created to track the availability of the repository in the cluster.

You can customise cluster labels to auto-apply packages. For more information, see Manage cluster labels.

Below is an example of using either of these selectors to filter for clusters with the stage nonprod and the name test.

selector:
  matchLabels:
    appvia.io/stage: nonprod
    name: test

selector:
  matchExpressions:
    - key: appvia.io/stage
      operator: In
      values: [nonprod]
    - key: name
      operator: In
      values: [test]

Manifest Descriptions​

Packages​

To show all packages use wf get packages.

➜  ~ wf get package
NAME                           STATUS     AGE      VERSION
aerospike-operator             Success    57d      2.4.0
aad-pod-identity               Success    57d      4.1.12-1
cert-manager                   Success    57d      1.9.1-1
cluster-autoscaler             Success    57d      9.21.0-2
external-dns-aws               Success    57d      6.2.4-1
external-dns-azure             Success    57d      6.2.4-1
external-dns-gcp               Success    50d      6.2.4-1
ingress-nginx                  Success    57d      4.2.0-1
kyverno                        Success    57d      2.6.5-1
metrics-server                 Success    57d      3.8.2-1
nvidia-device-plugin           Success    5d18h    v0.14.0
psa-operator                   Success    57d      0.0.9-1
terranetes-controller-aws      Success    49d      v0.4.2-3
terranetes-controller-azure    Success    49d      v0.4.2-3
tigera-operator                Success    57d      3.23.2-1

To show the manifest for a particular package you can output to stdout or to a file. Use 'wf get package NAME-OF-PACKAGE -o yaml' to output to stdout.

Note:

  • kind is set to Package
  • installNamespace describes the installation namespace where the Helm release should be installed in the clusters.
  • matchLabels and/or matchExpressions describes the installation target on which to match i.e., in the example it targets all the AWS (i.e. EKS) clusters.
  • url property points to the source of the Helm chart. It must match the Repository's url property.
  • version is the target version of the package to install.

➜  ~ wf get package nvidia-device-plugin -o yaml
apiVersion: package.appvia.io/v2beta1
kind: Package
metadata:
  name: aerospike-operator
spec:
  installNamespace: aerospike
  name: Aerospike
  releaseName: aerospike
  selectors:
    matchExpressions:
      - key: appvia.io/managementcluster
        operator: DoesNotExist
      - key: appvia.io/channel
        operator: In
        values:
          - EKS
  source:
    helm:
      name: aerospike-kubernetes-operator
      url: https://aerospike.github.io/aerospike-kubernetes-enterprise
      version: 2.4.0
  summary: Provides the ability to self service Aerospike databases
  values: {}
  version: 2.4.0

Repositories​

To show all repositories use wf get repositories.

➜  ~ wf get repository
NAME                    STATUS     AGE
aerospike               Success    6d
nvidia-device-plugin    Success    5d18h

To show the manifest for a particular repository you can output to stdout or to a file. Use 'wf get repository NAME-OF-REPOSITORY -o yaml' to output to stdout.

Note:

  • kind is set to Repository
  • interval describes the interval in which to check for new updates.
  • url property points to the external repository where the source files exist. It must match the Package's url property.

➜  ~ wf get repository aerospike -o yaml
apiVersion: package.appvia.io/v2beta1
kind: Repository
metadata:
  name: aerospike
spec:
  url: https://aerospike.github.io/aerospike-kubernetes-enterprise
  interval: 60m
  timeout: 60s
  suspend: false


PackageRelease​

To show all package releases use wf get packagerelease.


➜  ~ wf get packagerelease
NAME                                     CLUSTER      STATUS     AGE
eks-opdar-aerospike-operator             eks-opdar    Success    9d
eks-opdar-aad-pod-identity               eks-opdar    Success    9d
eks-opdar-cert-manager                   eks-opdar    Success    9d
eks-opdar-external-dns-azure             eks-opdar    Success    9d
eks-opdar-ingress-nginx                  eks-opdar    Success    9d
eks-opdar-kyverno                        eks-opdar    Success    9d
eks-opdar-terranetes-controller-azure    eks-opdar    Success    9d
➜  ~

To show the manifest for a particular PackagerRelease you can output to stdout or to a file. Use 'wf get packagerelease NAME-OF-PACKAGERELEASE -o yaml' to output to stout.

Note:

  • kind is set to PackageRelease
  • namespace points to the particular cluster label that this PackageRelease targets. There will be multiple PackageReleases depending on the number of matches that meets the matchExpressions property, as described in the Package's manifest.
  • package property describes the package configuration for the package installation.
  • selectors describes the particular workspace-cluster/cloud-provider labels that this PackageRelease targets
  • source points to the HelmRelease target on the workspace cluster

apiVersion: package.appvia.io/v2beta1
kind: PackageRelease
metadata:
  name: eks-aerospike-operator
  namespace: sandbox
spec:
  clusterRef:
    group: compute.appvia.io
    kind: Cluster
    name: eks
    namespace: sandbox
    version: v2beta1
  package:
    installNamespace: aerospike
    name: Aerospike
    releaseName: aerospike
    selectors:
      matchExpressions:
      - key: appvia.io/managementcluster
        operator: DoesNotExist
      - key: appvia.io/channel
        operator: In
        values:
        - default
      - key: appvia.io/workspace
        operator: In
        values:
        - sandbox
      - key: appvia.io/name
        operator: In
        values:
        - eks
      - key: appvia.io/provider
        operator: In
        values:
        - EKS
    source:
      helm:
        name: aerospike-kubernetes-operator
        url: https://aerospike.github.io/aerospike-kubernetes-enterprise
        version: 2.4.0
    summary: Provides the ability to self service Aerospike databases
    values: {}
    version: 2.4.0
  packageRef: aerospike-operator
  revision: "1"

RepositoryRelease​

To show all repository releases use wf get repositoryrelease.


➜  ~ wf get repositoryrelease
NAME                              CLUSTER      STATUS     AGE
eks-opdar-aerospike               eks-opdar    Success    6d2h
eks-opdar-nvidia-device-plugin    eks-opdar    Success    5d20h

To show the manifest for a particular RepositoryRelease you can output to stdout or to a file. Use 'wf get repositoryrelease NAME-OF-REPOSITORYRELEASE -o yaml' to output to stdout.

Note:

  • kind is set to RepositoryRelease
  • namespace points to the particular cluster label that this PackageRelease targets. There will be multiple PackageReleases depending on the number of matches that meets the matchExpressions property, as described in the Package manifest.
  • package property describes the package configuration for the package installation.
  • selectors describes the particular workspace-cluster/cloud-provider labels that this PackageRelease targets
  • source points to the HelmRelease target on the workspace cluster

apiVersion: package.appvia.io/v2beta1
kind: RepositoryRelease
metadata:
  name: eks-aerospike
  namespace: sandbox
spec:
  clusterRef:
    group: compute.appvia.io
    kind: Cluster
    name: eks
    namespace: sandbox
    version: v2beta1
  repository:
    interval: 60m
    selectors: {}
    timeout: 60s
    url: https://aerospike.github.io/aerospike-kubernetes-enterprise
  revision: "1"

Mapping values from resources​

Packages support rendering values from a number of objects. In all cases, if the resource being referenced is not available, or the key being extracted does not exist in the resource, the package is placed into a pending status and will continuously requeue every 60 seconds.


Using Secrets​

You can reference non-system managed secrets using the following:

valuesFrom:
  - secret:
      name: <name of secret>
      key:  <key inside the secret>
      path: <helm value path to map value>

note

Referencing secrets across workspaces is only available to Wayfinder administrators.


As a Wayfinder administrator, you can reference a secret from another workspace by adding the namespace field. It can be useful to reference some secrets across workspaces, for example, monitoring tokens. Note that because members of a workspace have access to the cluster.admin role, they would be able to see any secrets in the cluster. To disable this you would need to enforce a policy that specifically denies access to the secret.


Creating Secrets​

You can use the CLI to create managed secrets using wf create secret.


Using resources​

You can reference any object within the workspace using the following:

valuesFrom:
  - resource:
      group: compute.appvia.io
      version: v1alpha1
      kind: Cluster
      name: <name of resource>
      key: <json path into the resource>
      path: <json path into the helm values>

note

Any secret within the workspace that is system managed (i.e. they were not added by a user) cannot be referenced using the above.


Referencing cluster resources​

Cluster references are shortcuts to the above resource type selector. So when you type:

valuesFrom:
  - cluster:
      key: <json path into the resource>
      path: <json path into the helm values>

Internally, this is converted to:

valuesFrom:
  - resource:
      group: compute.appvia.io
      version: v1alpha1
      kind: Cluster
      name: <name of cluster the package is bound>
      key: <json path into the resource>
      path: <json path into the helm values>

Apply packages​

As a Wayfinder administrator, you can apply Packages and Repositories manually. After you have defined and applied the manifests, Wayfinder will automatically create the PackageRelease and RepositoryRelease and install the package on the cluster that matches the package label selectors, in any workspace. You will do this for packages that are not managed by Wayfinder. Wayfinder's managed packages refer to those packages that are shipped with Wayfinder's installation i.e. ingress-nginx.

To apply a package:

  1. Run the applicable CLI commands below.
  • Package: wf apply PACKAGE.yaml
  • Repository: wf apply REPOSITORY.yaml

Troubleshooting Logs​

If something goes wrong, you can examine the logs from the helm-controller pod in the wf-manager namespace on a cluster. To do so you'll need to access the cluster using the cluster.admin role:

wf access cluster CLUSTER-NAME --role cluster.admin.

Last updated on 30 Apr 2024