Chapter 1. Managing applications

From the Overview tab of the dashboard for a single application, you can complete the following tasks:

From the Resources tab for a single application, you can complete the following tasks:

You can use channels and subscriptions to manage the continuous delivery of deployables, such as Helm charts and Kubernetes deployable objects, to your managed clusters or other namespaces.

When a channel points to a Helm repository, the channel operator creates a deployable to represent each Helm release that is found in the repository.

For Kubernetes deployable objects, you can add the objects to a channel by wrapping them as deployables.

Within the deployable definition you can directly specify a channel where the deployable is to be promoted. You can also specify the required Kubernetes labels for the deployable to match the gate requirements for a channel to have the deployable automatically added to a channel. When the channel controller detects that the deployable includes the required Kubernetes labels, the controller promotes the deployable to the channel.

When creating a Namespace and ObjectBucket channel, you can set the channel gate requirements within the spec.gates section of the channel definition. These requirements are Kubernetes annotations that a deployable must include before the deployable can be promoted to the channel. For instance, you can specify annotations for development approvals, test and quality assurance approval, and to indicate a deployable is ready for deployment to a production environment cluster. These gate requirements can be any field and value, such as the source namespace, package name, labels, and annotations. A deployable can be promoted in a channel only when the deployable definition includes the matching fields and values. When a deployable meets the defined requirements, the deployable is automatically promoted to the channel and deployed to any managed clusters that subscribe to the channel. Gate requirements do not apply for HelmRepo and Git channel types.

For channels that do not include gate requirements, the channel controller promotes the latest version of a deployable to the channel.

Clusters can subscribe to channels for identifying the deployables to deploy to each cluster. Deployables that are promoted to a channel can be accessed by only the subscriptions for that channel. When channels and subscriptions exist, the channels and subscriptions work together to retrieve deployables from the channel source and place the deployables at the destination. The destination is typically a managed cluster, which is abstracted as a namespace. A managed cluster or namespace can subscribe to multiple channels for identifying the deployables to deploy to the cluster. Channels ensure that the correct deployable is available for retrieval. Subscriptions ensure that the deployable is retrieved and placed on the destination namespaces or clusters. For retrieving a deployable, the subscription operator checks the annotation limits and determines whether to retrieve and apply the deployable to the managed cluster.

Channels do not have a status, while a subscription that subscribes to a channel does have a status. The status for a subscription reports whether the subscription is successfully propagated on the hub cluster, and whether the subscription successfully created or applied a deployable template or created the helmRelease CR. The status for the deployables that are deployed through the use of channels and subscriptions are reported separately from the subscription.

Since channels do not have a status, the resources that are promoted to a channel namespace are not always synchronized with the actual channel storage.

When a deployable is included within a channel or updated, the subscription operator for the channel detects the new or updated deployable automatically. You do not need to issue any notification from the hub cluster to the target managed clusters.

For a subscription to a namespace type channel, resources are synchronized for a managed cluster only while the cluster can access the channel namespace. Since the channel source exists on the hub cluster, the subscription can only pull the resources from the source when access to the hub cluster exists.

For subscriptions to Helm repository and object store type channels, the subscription watches the channel source repositories for new or updated Helm charts or deployables. The subscriptions do not need to communicate with the hub cluster unless the source repository is on the hub cluster. If subscriptions are set up to pull the latest version for a Helm release or deployable object, and new versions are included in the repository types, the subscriptions can retrieve the versions.

You can create Kubernetes secret resources to store authorization credentials and other sensitive information for your subscriptions and application components.

Samples for resources, including secrets, are located in the Application resource samples documentation.

After your subscription is created, your subscription can have one of the following statuses:

If you created the subscription for a multi-cluster environment, the subscription is created on the Hub cluster. Depending on your spec.placement settings, the subsequent placement of your subscription on other clusters is different. If you include more than one placement setting within the spec.placement section, the subscription operator uses the following priority to select the placement setting to use:

If you created your subscription on a stand-alone cluster or a cluster that you want to manage directly, the subscription is created on only that cluster. Depending on the value that you set for the spec.placement.local field within the subscription definition, the subsequent behavior of your subscription is different.

To associate a subscription with an application, both the subscription and application must be in the same namespace so that the subscription can retrieve Helm charts, deployables, or other resources from a channel.

Within the application resource definition, the definition must include spec.componentKinds settings to indicate that the application uses a subscription. The definition must also include spec.selector settings to define the labels (matchLabels) or expressions (matchExpressions) to use to match the application with the subscription.

Within the subscription resource definition, the definition must include the required values to match the labels or expressions that are defined by the application.

When the subscription is associated with an application, the subscription uses the spec.placement settings for the subscription or deployable to deploy any subscribed charts, deployables or other Kubernetes resources for the application.

For more information about the resource definition for an application, see Creating and managing application resources.

If you need to deploy new or change Helm charts or other resources during only specific times, you can define subscriptions for those resources to begin deployments during only those specific times. Alternatively, you can restrict deployments from beginning during specific time windows, such as to avoid unexpected deployments during peak business hours.

For instance, you can define time windows between 10:00 PM and 11:00 PM each Friday to serve as scheduled maintenance windows for applying patches or other application updates to your clusters.

Alternatively, you can restrict or block deployments from beginning during specific time windows, such as to avoid unexpected deployments during peak business hours. For instance, to avoid peak hours you can define a time window for a subscription to avoid beginning deployments between 8:00 AM and 8:00 PM.

By defining time windows for your subscriptions, you can coordinate updates for all of your applications and clusters. For instance, you can define subscriptions to deploy only new application resources between 6:01 PM and 11:59 PM and define other subscriptions to deploy only updated versions of existing resources between 12:00 AM to 7:59 AM.

When a time window is defined for a subscription, the time ranges when a subscription is active changes. As part of defining a time window, you can define the subscription to be active or blocked during that window. The deployment of new or changed resources begins only when the subscription is active. Regardless of whether a subscription is active or blocked, the subscription continues to monitor for any new or changed resource. The active and blocked setting affects only deployments.

When a new or changed resource is detected, the time window definition determines the next action for the subscription.

If a deployment begins during a defined time window and is running when the defined end of the time window elapses, the deployment continues to run to completion.

To define a time window for a subscription, you need to add the required fields and values to the subscription resource definition YAML.

Configure package overrides for a subscription override value for the Helm chart or Kubernetes resource that is subscribed to by the subscription.

To configure a package override, specify the field within the Kubernetes resource spec to override as the value for the path field. Specify the replacement value as the value for the value field.

For example, if you need to override the values field within the spec for a Helm release for a subscribed Helm chart, you need to set the value for the path field in your subscription definition to spec.

packageOverrides:
- packageName: nginx-ingress
  packageOverrides:
  - path: spec
    value: my-override-values

The contents for the value field are used to override the values within the spec field of the HelmRelease spec.

To delete a subscription, you can use the console, the Kubernetes command line interface (kubectl) tool, or REST API.

To use the console, complete the following procedure:

To use the Kubernetes CLI tool:

To use REST API, use the APIs.

Placement rules can be defined for subscriptions and for deployables. Define the placement rule at the subscription level for multi-cluster deployments. Define the placement rule for a specific deployable for single-cluster deployments or to override placement settings.

Prerequisite: Be sure the klusterlet-addon-appmgr pod is running. You can run oc get pods -n open-cluster-management-agent-addon to check for pods.

As a best practice, define placement rules as a separate resource when the rule might need to be referenced by multiple resources.

+ To create a placement rule as a separate resource, you can use the console, the Kubernetes CLI (kubectl) tool, or REST API:

You can assign a placement rule to a deployable or subscription. To assign a placement rule, you need to update the spec for the deployable or subscription to reference the placement rule.

Include the following placement fields in your deployable or subscription spec with the values to reference the placement rule:

placement:
  placementRef:
    name:
    kind: PlacementRule

Include the name of your placement rule as the value for the name field.

When a placement rule is assigned to a subscription, you can view the assignment on the Applications dashboard within the console with the following procedure:

When a placement rule is created and in use, you can view the status details for the rule. This status is appended to the YAML definition for a placement rule and indicates the target clusters where the rule is used for placing deployables.

To view the status fields for a placement rule, you can use the console, the Kubernetes command line interface (kubectl) tool, or REST API.

To use REST API, use the APIs

To update a placement rule that is a separate resource, you can use the console, the Kubernetes command line interface (kubectl) tool, or REST API.

To use REST API, use the APIs.

To update a placement rule that is defined within the definition for a deployable or subscriptions, the steps are the same as for updating that resource.

To delete a placement rule that is a separate resource, you can use the console, the Kubernetes command line interface (kubectl) tool, or REST API.

To use the console, complete the following procedure:

To use the Kubernetes CLI tool, complete the following steps:

To use REST API, use the APIs.

To use REST API, use the APIs.

To delete an application, you can use the console, the Kubernetes command line interface (kubectl) tool, or REST API:

To use the console, complete the following steps:

To use the Kubernetes CLI tool, complete the following steps:

To use REST API, use the APIs.

To set up and use channels, subscriptions, and placement rules for deployments, complete the following procedure:

A placement rule can be defined for a subscription and for deployables. Define the placement rule for a subscription to have the rule apply to multiple deployables and clusters. Define the placement rule for a deployable to prevent the rule from applyin to all deployables for the subscription, or when you want to override a subscription-level placement rule. ** If you are referencing a placement rule, you can also include override settings for a deployable to override some placement rule values with values specific to the deployable. . Optional. If you created the placement rule as a stand-alone resource, edit the definition for your subscription or deployables to reference your placement rule. . Edit the definition for your deployables and your channel to ensure that deployables are promoted to the channel. For more information, see the Promoting a deployable to a channel section. . Use the console to monitor the status of the deployment to the target cluster or clusters for the channel.

To promote a deployable, which is a resource template, to a channel, you can use any of the following methods:

The following example subscription indicates that the most recent nginx version 1.x chart is to be promoted through the channel for deployment with the subscription.

```yaml
apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
   name: mydevsub
   namespace: myspace
spec:
 source: https://kubernetes-charts.storage.googleapis.com/
 package: nginx
 packageFilter:
   version: 1.x
 placement:
   clusters:
   - name: mydevcluster1
```

View samples and YAML definitions that you can use to build your files. Channels (channel.apps.open-cluster-management.io) provide you with improved continuous integration and continuous delivery capabilities for creating and managing your Red Hat Advanced Cluster Management for Kubernetes applications. Learn more at Creating and managing channels.

apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
  name:
  namespace: # Each channel needs a unique namespace, except Git channel.
spec:
  sourceNamespaces:
  type:
  pathname:
  secretRef:
    name:
  gates:
    annotations:
  labels:

apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
  name: predev-ch
  namespace: ns-ch
  labels:
    app: nginx-app-details
spec:
  type: HelmRepo
  pathname: https://kubernetes-charts.storage.googleapis.com/

  apiVersion: apps.open-cluster-management.io/v1
  kind: Channel
  metadata:
    name: qa
    namespace: ch-qa
  spec:
    sourceNamespaces:
    - default
    type: Namespace
    pathname: ch-qa
    gates:
      annotations:
        dev-ready: approved

apiVersion: apps.open-cluster-management.io/v1
kind: Deployable
metadata:
  labels:
    app: gbchn
    apps.open-cluster-management.io/channel: gbchn
    apps.open-cluster-management.io/channel-type: Namespace
    release: gbchn
  name: gbchn-service
  namespace: gbchn
spec:
  template:
    apiVersion: v1
    kind: Service
    metadata:
      labels:
        app: gbchn
        release: gbchn
      name: gbchn
    spec:
      ports:
      - port: 80
      selector:
        app: gbchn

apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
 name: dev
 namespace: ch-obj
spec:
 type: ObjectBucket
 pathname: [http://9.28.236.243:31311/dev] # URL is appended with the valid bucket name, which matches the channel name.
 secretRef:
   name: miniosecret
 gates:
   annotations:
     dev-ready: true

apiVersion: v1
kind: Namespace
metadata:
  name: hub-repo
---
apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
  name: helm
  namespace: hub-repo
spec:
    pathname: [https://9.21.107.150:8443/helm-repo/charts] # URL points to a valid chart URL.
    configRef:
      name: insecure-skip-verify
    type: HelmRepo
---
apiVersion: v1
data:
  insecureSkipVerify: "true"
kind: ConfigMap
metadata:
  name: insecure-skip-verify
  namespace: hub-repo

apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
  name: predev-ch
  namespace: ns-ch
  labels:
    app: nginx-app-details
spec:
  type: HelmRepo
  pathname: https://kubernetes-charts.storage.googleapis.com/

apiVersion: apps.open-cluster-management.io/v1
kind: Channel
metadata:
  name: hive-cluster-gitrepo
  namespace: gitops-cluster-lifecycle
spec:
  type: Git
  pathname: https://github.com/open-cluster-management/gitops-clusters.git
  secretRef:
    name: github-gitops-clusters
---
apiVersion: v1
kind: Secret
metadata:
  name: github-gitops-clusters
  namespace: gitops-cluster-lifecycle
data:
  user: dXNlcgo=            # Value of user and accessToken is Base 64 coded.
  accessToken: cGFzc3dvcmQ

apiVersion: v1
kind: Secret
metadata:
  annotations:
      apps.open-cluster-management.io/deployables: "true"
  name: [secret-name]
  namespace: [channel-namespace]
data:
  AccessKeyID: [ABCdeF1=] #Base64 encoded
  SecretAccessKey: [gHIjk2lmnoPQRST3uvw==] #Base64 encoded

View samples and YAML definitions that you can use to build your files. As with channels, subscriptions (subscription.apps.open-cluster-management.io) provide you with improved continuous integration and continuous delivery capabilities for application management. Learn more at Creating and managing subscriptions.

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name:
  namespace:
  labels:
spec:
  sourceNamespace:
  source:
  channel:
  name:
  packageFilter:
    version:
    labelSelector:
      matchLabels:
        package:
        component:
    annotations:
  packageOverrides:
  - packageName:
    packageAlias:
    - path:
      value:
  placement:
    local:
    clusters:
      name:
    clusterSelector:
    placementRef:
      name:
      kind: PlacementRule
  overrides:
    clusterName:
    clusterOverrides:
      path:
      value:

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: nginx
  namespace: ns-sub-1
  labels:
    app: nginx-app-details
spec:
  channel: ns-ch/predev-ch
  name: nginx-ingress
  packageFilter:
    version: "1.36.x"
  placement: # Placement rules help you facilitate multi-cluster deployments, see placement rules documentation.
    placementRef:
      kind: PlacementRule
      name: towhichcluster
  overrides: # See Deployable documentation for more about overrides. Include overrides for any single cluster than requires some different settings
  - clusterName: "/"
    clusterOverrides:
    - path: "metadata.namespace"
      value: default

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: nginx
  namespace: ns-sub-1
  labels:
    app: nginx-app-details
spec:
  channel: ns-ch/predev-ch
  name: nginx-ingress

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: nginx
  namespace: ns-sub-1
  labels:
    app: nginx-app-details
spec:
  channel: ns-ch/predev-ch
  name: nginx-ingress
  packageFilter:
    version: "1.36.x"
  placement:
    placementRef:
      kind: PlacementRule
      name: towhichcluster
  timewindow:
    windowtype: "active" #Enter active or blocked depending on the purpose of the type.
    location: "America/Los_Angeles"
    daysofweek: ["Monday", "Wednesday", "Friday"]
    hours:
      - start: "10:20AM"
        end: "10:30AM"
      - start: "12:40PM"
        end: "1:40PM"

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: simple
  namespace: default
spec:
  channel: ns-ch/predev-ch
  name: nginx-ingress
  packageOverrides:
  - packageName: nginx-ingress
    packageAlias: my-nginx-ingress-releaseName
    packageOverrides:
    - path: spec
      value:
        defaultBackend:
          replicaCount: 3
  placement:
    local: false

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: nginx
  namespace: ns-sub-1
  labels:
    app: nginx-app-details
spec:
  channel: ns-ch/predev-ch
  name: nginx-ingress
  packageFilter:
    version: "1.36.x"
  placement:
    clusters:
    - name: my-development-cluster-1
  packageOverrides:
  - packageName: my-server-integration-prod
    packageOverrides:
    - path: spec
      value:
        persistence:
          enabled: false
          useDynamicProvisioning: false
        license: accept
        tls:
          hostname: my-mcm-cluster.icp
        sso:
          registrationImage:
            pullSecret: hub-repo-docker-secret

    apiVersion: apps.open-cluster-management.io/v1
    kind: Subscription
    metadata:
      name: sample-subscription
      namespace: default
      annotations:
        apps.open-cluster-management.io/git-path: sample_app_1/dir1
        apps.open-cluster-management.io/git-branch: branch1
    spec:
      channel: default/sample-channel
      placement:
        placementRef:
          kind: PlacementRule
          name: dev-clusters

apiVersion: apps.open-cluster-management.io/v1
kind: Subscription
metadata:
  name: example-subscription
  namespace: default
spec:
  channel: some/channel
  packageOverrides:
  - packageName: kustomization
    packageOverrides:
    - value: |
patchesStrategicMerge:
- patch.yaml

  oc create route passthrough --service=multicluster-operators-subscription -n open-cluster-management

https://<externally-reachable hostname>/webhook`

apiVersion: v1
kind: Secret
metadata:
  name: my-github-webhook-secret
data:
  secret: BASE64_ENCODED_SECRET

oc annotate channel.apps.open-cluster-management.io <channel name> apps.open-cluster-management.io/webhook-enabled="true"

oc annotate channel.apps.open-cluster-management.io <channel name> apps.open-cluster-management.io/webhook-secret="<the_secret_name>"

Placement rules (placementrule.apps.open-cluster-management.io) define the target clusters where deployables can be deployed. Use placement rules to help you facilitate the multi-cluster deployment of your deployables.

apiVersion: apps.open-cluster-management.io/v1
kind: PlacementRule
  name:
  namespace:
  resourceVersion:
  labels:
    app:
    chart:
    release:
    heritage:
  selfLink:
  uid:
spec:
  clusterSelector:
    matchLabels:
      datacenter:
      environment:
  clusterReplicas:
  clusterConditions:
  ResourceHint:
    type:
    order:
  Policies:

status:
  decisions:
    clusterName:
    clusterNamespace:

apiVersion: apps.open-cluster-management.io/v1
kind: PlacementRule
metadata:
  name: gbapp-gbapp
  namespace: development
  labels:
    app: gbapp
spec:
  clusterSelector:
    matchLabels:
      environment: Dev
  clusterReplicas: 1
status:
  decisions:
    - clusterName: local-cluster
      clusterNamespace: local-cluster

apiVersion: apps.open-cluster-management.io/v1
kind: PlacementRule
metadata:
  name: towhichcluster
  namespace: ns-sub-1
  labels:
    app: nginx-app-details
spec:
  clusterReplicas: 1
  clusterConditions:
    - type: ManagedClusterConditionAvailable
      status: "True"
  clusterSelector:
    matchExpressions:
    - key: environment
      operator: In
      values:
      - dev

View samples and YAML definitions that you can use to build your files. Applications (Application.app.k8s.io) in Red Hat Advanced Cluster Management for Kubernetes are used for viewing the application components.

For more information about creating and managing applications, see Creating and managing application resources.

apiVersion: app.k8s.io/v1beta1
kind: Application
metadata:
  name:
  namespace:
  resourceVersion:
  annotations:
  labels:
    app:
    chart:
    heritage:
    name:
    release:
spec:
  componentKinds:
  - group:
    kind:
  descriptor:
  selector:
    matchExpressions:
    - key:
      operator:
      values:

apiVersion: app.k8s.io/v1beta1
kind: Application
metadata:
  labels:
    app: nginx-app-details
  name: nginx-app-3
  namespace: ns-sub-1
spec:
  componentKinds:
  - group: apps.open-cluster-management.io
    kind: Subscription
  selector:
    matchLabels:
      app: nginx-app-details
status: {}