EC Deployment Patch Examples(4.3)

An ECD Patch is meant to provide a flexible option to define and provision Kubernetes objects that suit your system architecture, or to tailor the ECD to their preferred flavor.

Note!

An ECD Patch is NOT the same as using the kubectl patch command. Although they are conceptually similar, they do not necessarily behave in the same way.

Introduction

The ECD patch functionality enables you to add, change, and remove certain fields and functionality that might not be supported directly in the ECD specification, from the different Kubernetes objects created by the Operator through the ECD specification. The patch and patchType fields are part of the ECD CRD structure.

The operator expects the ECD patch to be in YAML format with respective parameters according to the patching strategy. The operator will attempt to patch the user-defined YAML with the original YAML, resulting in one YAML before applying it to the Kubernetes cluster.

The ECD patch functionality can be used either from Desktop Online or directly in the ECD specification YAML.

Note that parameters defined by Usage Engine in the ECD specification (Workflows, Workflow Groups) cannot be patched with the ECD Patch functionality. You can however, of course, edit these parameters directly in the ECD specification and apply the changes to the cluster.

Patch Format

The Patch format consists of 2 fields; patch and patchType, embedded under different Kubernetes objects. The patch field is the payload itself, which will be used to patch into the ECD Kubernetes objects. patchType is the field where users can define the patching strategies used to patch the payload.

Currently, the following objects can be patched through ECD:

ECD (Deployments and Pods)
Services
HPA/autoscaling
Ingress

Below is an example of the structure under ECD (spec.patch and spec.patchType) :

apiVersion: mz.digitalroute.com/v1alpha1
kind: ECDeployment
metadata:
  name: anyECDeployment
  namespace: anyNamespace
spec:
  ...
  ...
  patchType: "application/merge-patch+json"
  patch: |
        ...
        ...

Below is an example of the structure under HPA (spec.autoscale.patch and spec.autoscale.patchType):

apiVersion: mz.digitalroute.com/v1alpha1
kind: ECDeployment
metadata:
  ...
spec:
  autoscale:
    ...
    ...
    patchType: "application/merge-patch+json"
    patch: |
      spec:
        ...

Note!

There is a pipe “|” right after Patch, to indicate that the lines below are multi-lines YAML

In Desktop Online you can find the corresponding patch for ECD (deployment and pods), Services, HPA/autoscaling, and Ingress (Ingress also being under networking) under their respective ECD sections:

ECD (deployment and pods) Patch functionality in Desktop Online

ECD Patch for services (adding two service ports through patch)

Patching Strategies

There are 3 types of strategies supported by the ECD Patch feature:

JSON Patch (RFC6902)
Merge Patch (RFC7386)
Strategic Merge Patch (Kubernetes custom implementation of Merge Patch)

JSON Patch

As defined in RFC6902, a JSON Patch is a sequence of operations that are executed on the resource, e.g. {"op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ]}. For more details on how to use the JSON Patch, see the RFC.

The example below shows how you annotate an Ingress resource so that it can be managed by Istio:

apiVersion: mz.digitalroute.com/v1alpha1
kind: ECDeployment
metadata:
  ...
spec:
  ...
  ingress:
    patchType: "application/json-patch+json"
    patch: |
      - op: replace
        path: /metadata/annotations/Kubernetes.io~1ingress.class
        value: istio

Changing an item in a list

In order to change an item in a list you can do this conveniently with JSON Patch. In the example below we change the service port from 1234 to 1235. The zero in the path (/spec/ports/0/port) specifies that the first item in the list should be changed.

Merge Patch

As defined in RFC7386, a Merge Patch is a partial representation of the resource. The submitted JSON is "merged" with the current resource to create a new one, then the new one is saved. For more details on how to use Merge Patch, see the RFC.

The example below shows how you add a node selector to restrict this deployment (pod) to only run on nodes with a label where the disk type is SSD:

Strategic Merge Patch

Strategic Merge Patch is a custom implementation of Merge Patch for Kubernetes. For a detailed explanation of how it works and why it had to be introduced, see API Conventions on Patch - Strategic Merge. In general, Strategic Merge Patch works better when merging Kubernetes objects in a list.

In this ECD Services, port 9092 is already defined. Using Strategic Merge Patch, you can add two more ports 9093 and 9094. If you were to change the type from a Strategic Merge Patch to a Merge Patch in this case, port 9092 would have been removed after the patch.

Here is an example changing multiple (sub-)paths in the same deployment/pod patch (also using Strategic Merge Patch):

Samples

Below are samples that can help you get started with an ECD patch. The “Before” section is based on the ECD, which is the definition file for the desired state. while the “After” section is based on the conversion and logic processing done by Operator - which is the actual objects provisioning yaml to be applied to the cluster. As you can see, there are several objects that will be provisioned and handled by the Operator itself.

Changing Rollout Strategy

Creating an ECD will result in the creation of different Kubernetes objects, where one of them is a Deployment object. The rollout strategy defaults to RollingUpdate, but through an ECD patch we can change it to another strategy such as Recreate. The change can be seen on the spec.strategy.type in the Deployment object After ECD Patch.

Before ECD Patch	After ECD Patch

Before ECD Patch	After ECD Patch
`kubectl apply -f file.yaml`	`kubectl get deploy ecd-test-rolling-strategy -o yaml`

Setting Toleration

In the example below, with a 3 node implementation of a Kubernetes cluster, 2 nodes are tainted color=blue and 1 node is tainted color=red. The test is to add toleration to ECD so that it will get deployed into node tainted with color=red.

Observe how toleration is being added and gets scheduled to the node tainted with color=red.

Before ECD Patch	After ECD Patch

Before ECD Patch

After ECD Patch

kubectl apply -f file.yaml

kubectl get pods ecd-test-tolerations-5d646c45cd-g9x8n -o wide

kubectl describe pods ecd-test-tolerations-5d646c45cd-g9x8n| grep -i toleration

Setting Environment Variable

You can also add in an environmental variable. In the example below, the environmental variable ENV is added with the value “dev”.

Before ECD Patch	After ECD Patch

Before ECD Patch

After ECD Patch

kubectl apply -f file.yaml

kubectl exec ecd-test-2-7487469546-s77xx -- /bin/bash printenv | grep ENV

kubectl describe pods ecd-test-2-7487469546-s77xx

Removing an Object

You can also use this functionality to remove a provisioned Kubernetes object. In the example below, the directive marker ($patch: delete) is used to remove a volume and volumeMount.

Before ECD Patch	After ECD Patch

Before ECD Patch	After ECD Patch
`kubectl apply -f file.yaml`	`kubectl get pods ecd-test-2-678ccb76d6-s49ql -o yaml`