CRD Conversion Webhook

Overview

The Cloud-Native Network Functions (CNFs) 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. However, CRDs with only one version (for example v1) will not have a conversion strategy. This is a node port service.

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

conversion:
 strategy: Webhook
 webhook:
   clientConfig:
     caBundle: ""
     service:
       name: crdconversion-webhook-svc
       namespace: cnf-crdconversion
       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 cnf-crdconversion. Refer to CRD Conversion Namespace section.
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: cnf-crdconversion/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.

CRD Conversion Namespace

By default, the CRD Conversion pod is deployed in the ‘default’ namespace. If you want to change its namespace, you need to specify the desired namespace in the crd-values.yaml file during the CNFs CRD Bundles deployment.

In this example, the CRD Conversion Pod is installed in cnf-crdconversion namespace.

conversion:
  namespace: cnf-crdconversion

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
      ## Namespace where rabbitmq is deployed
      rabbitmqNamespace: "default"
      ## crd conversion image values
      image:
        repository: artifactory.f5net.com/f5-f5ingress-docker
        name: crd-conversion
        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 0.9.4-0.0.3 -n cnf-crdconversion 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 cnf-crdconversion Project.

    oc get pod -n cnf-crdconversion 
    

    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 cnf-crdconversion 
    

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

    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: cnf-crdconversion/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: cnf-crdconversion
             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
    
  2. After the CRD Conversion Pod is deployed, we will allow multi-tenancy with different versions of F5Ingress and other pods deployed on it. And, also support multiple versions of CRs and CRDs.

Feedback

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