CRD Conversion Webhook

Overview

The Service Proxy for Kubernetes (SPK) CRD (Custom Resource Definition) Conversion Webhook is a mechanism or set of tools designed to handle the automatic conversion of multiple CRD versions from older to newer based on the specified namespace and version of the CRD. It addresses issues related to attribute addition, modification, and deletion in the cluster.

Requirements

Ensure you have:

CRD Webhook Conversion Strategy Configuration

The CRD Webhook Conversion Strategy configurations has been added to all the CRDs by default to support multiple version conversion.

In this example, details the configurations of CRD Webhook Conversion Strategy:

conversion:
 strategy: Webhook
 webhook:
   clientConfig:
     caBundle: ""
     service:
       name: crdconversion-webhook-svc
       namespace: default
       path: /f5-crd-converter
       port: 3128
   conversionReviewVersions: [v1,v2]

The table below describes the configuration parameters of the CRD Webhook Conversion Strategy added in the CRDs:

Parameter Description
conversion.strategy Specifies the conversion strategy is a Webhook. When a CRD is created, updated or deleted the API server call an external webhook for any conversion between custom resources.
conversion.webhook.clientConfig Specifies the client configuration for the webhook.
conversion.webhook.clientConfig.caBundle Specifies certificate bundle (CA bundle) used to validate the webhook server's TLS certificate.
conversion.webhook.conversionReviewVersions Specifies the API versions that the webhook server supports for conversion reviews.

Webhook Service Configuration:

Parameter Description
name Specifies the name of the service that exposes the webhook server is crdconversion-webhook-svc.
namespace Specifies the namespace in which the Service crdconversion-webhook-svc is deployed is default.
path Specifies the path to which the webhook server should listen for requests is /f5-crd-converter.
port Specifies port on which the webhook server listens for incoming requests is 3128.

Annotations

In this example, a cert-manager annotation is used to establish a connection to the conversion service and fill out the caBundle with the CA root certificate.

 annotations:
  cm.f5co.k8s.f5net.com/inject-ca-from: default/tls-crdconversion-webhook-svr

Template Fields Configuration

For example:

 names:
  kind: F5BigCneAddresslist
  plural: f5-big-cne-addresslists
  singular: f5-big-cne-addresslist
  shortNames:
   - addrlist

The table below describes the configuration template fields in the CRDs:

Parameter Description
names.kind Specifies the kind (type) of the Custom Resource.
names.plural Specifies the plural form of the Custom Resource's name. For example: f5-big-cne-addresslists.
names.singular Specifies the singular form of the Custom Resource's name. For example: f5-big-cne-addresslist.
names.shortNames Specifies the shortname for names.

Installation

Use the following steps to install the CRD Conversion pod:

  1. Create a Helm value file named crd-conversion-values.yaml and set the image.tag parameter with the latest version.

    In this example, image.tag is set to latest version in crd-conversion-values.yaml file.

    crdconversion:
      name: f5-crd-conversion
      enabled: true
      debug: false
      ## crd conversion image values
      image:
        repository: artifactory.f5net.com/f5-f5ingress-docker
        name: crd-conversion
        tag: v0.3.8
        pullPolicy: Always
      fluentbit_sidecar:
        # Enable/Disable sidecar
        enabled: false
    
  2. Install the CRD Conversion pod with latest version using Helm install:

    helm install f5-crd-conversion --version v0.3.8 -n default f5ingress-dev/f5-crdconversion -f crd-conversion-values.yaml  
    
  3. Verify the STATUS of the CRD Conversion pod:

    In this example, CRD Conversion Pod is installed in the default Project.

    oc get pod -n default
    

    As we can see CRD Conversion pod is created.

    NAME                                  READY      STATUS       RESTARTS      AGE
    f5-crd-conversion-8478b9y96-asfd1     1/1        Running      0             30s
    
  4. Obtain the ClusterIP service created for CRD Conversion pod:

    oc get svc -n default 
    

    In this example, CRD Conversion CLUSTER-IP service is 172.30.167.180 and the PORT(S) is 9750.

    NAME                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
    crdconversion-webhook-svc    ClusterIP   172.30.167.180   <none>        9750/TCP   2hr
    

CRD Conversion Webhook for Handling Multiple CRD Versions

Use the following steps to perform CRD conversion webhook to handle multiple CRD versions:

  1. Create a new CRD with the specified versions for conversion:

    An example of a CRD with conversion webhook strategy added.

     apiVersion: apiextensions.k8s.io/v1
     kind: CustomResourceDefinition
     metadata:
       name: f5-big-cne-addresslists.k8s.f5net.com
       annotations:
         cm.f5co.k8s.f5net.com/inject-ca-from: default/tls-crdconversion-webhook-svr
     spec:
      group: k8s.f5net.com
      versions:
      - name: v1
       served: true
       storage: false
     	...
      - name: v2
       served: true
       storage: true
     	...
     conversion:
       strategy: Webhook
       webhook:
         clientConfig:
           caBundle: ""
           service:
             name: crdconversion-webhook-svc
             namespace: default
             path: /f5-crd-converter
             port: 3128
           conversionReviewVersions: [v1,v2]
     names:
       kind: F5BigCneAddresslist
       plural: f5-big-cne-addresslists
       singular: f5-big-cne-addresslist
       shortNames:
         - addrlist
     scope: Namespaced
    
    oc create -f v1.yaml -n default   
    
  2. Ensure that F5Ingress is deployed in your specified namespace and configured with a webhook to define the supported CRD versions for conversion.

  3. The conversion pod receives a request that includes the desired version.

  4. After a specified interval of time, open the CRD again, and you will find that the conversion file has been updated with the latest required changes.

Feedback

Provide feedback to improve this document by emailing spkdocs@f5.com.