Instance Stack Migration

To be able to start migrating the Instance Stack, you need to have migrated all Kafka stacks.

This Instance Stack Migration needs to be executed for each Instance defined in your Axual installation.

Start new Rest-Proxy and Schema-Registry components

Objective

Come up with a new values.yaml file to start new Rest-Proxy and Schema-Registry components with axual-streaming-chart alongside existing axual-helm-charts Rest-Proxy and Schema-Registry components.

Execution

  1. Define a new Chart.yaml that defines as dependency the streaming:0.3.3 charts.

    Chart.yaml 
    apiVersion: v2
appVersion: "2024.1.3"
description: Instance Services with Streaming Charts
name: [existing-instance-name]
type: application
version: 0.1.0
dependencies:
  - name: "axual-streaming"
    version: "0.3.4"
    repository: "https://dev.axual.io/nexus/repository/axual-helm-stable"

  2. Create a new values.yaml that will deploy the new Rest-Proxy and Schema-Registry for an existing Instance.

    Disable the components expect rest-proxy and axual-schema-registry

    values.yaml 
    global:

  kafka:
    enabled: false

  apicurio:
    enabled: false

Rest-Proxy

  1. Copy the existing platform.instance.restproxy section from the existing Instance’s values.yaml file and place it in the axual-streaming.rest-proxy section so that you can replace some keys.

    values.yaml 
    axual-streaming:
  # Pay attention to the `-`
  rest-proxy:
    [existing-configuration at `platform.instance.restproxy`]

  2. Move the axual key inside a new config key

    existing_values.yaml 
    axual-streaming:
  rest-proxy:
    axual:
      [existing-value]
    new_values.yaml 
    axual-streaming:
  rest-proxy:
    config:
      axual:
        [existing-value]

    To be able to remove the Discovery API, the Rest Proxy will need to use static configuration.

  3. Add to the config.axual section the information of the tenant and the instance

    values.yaml 
    axual-streaming:
  rest-proxy:
    config:
      axual:
        tenant: [tenant-short-name]
        instance: [instance-short-name]

  4. Replace registerAcls key with a new kafkaInitContainer key section

    existing_values.yaml 
    axual-streaming:
  rest-proxy:
    registerAcls:
      principal: [existing-rest-proxy-client-certificate]
      principalChain: [existing-rest-proxy-client-full-chain-certificate]
      distributionPattern: [existing-pattern]
    new_values.yaml 
    axual-streaming:
  rest-proxy:
    kafkaInitContainer:
      # -- Kafka bootstrap servers to initialize
      bootstrapServers: "SSL://[kafka-bootstrap-url]:[kafka-bootstrap-port]"
      # -- Principal common name to give access to (should match tls.clientKeypairSecretName)
      principal: [existing-rest-proxy-client-full-chain-certificate]
      # -- Group prefix to give access to (usually {tenant}.{instance})
      groupPattern: [existing-pattern-with-replacement-of-dash-with-dot]
      # -- Topic prefix to give access to (usually {tenant}-{instance})
      topicPattern: [existing-pattern]
      tls:
        # -- Existing Keypair secret name
        keypairSecretName: [existing-secret-name-of-a-super-user-certificate]
        # -- Existing Keypair key name
        keypairSecretKeyName: [key-name-of-the-super-user-certificate]
        # -- Existing Keypair certificate name
        keypairSecretCertName: [certificate-name-of-the-super-user-certificate]
        # -- Existing Truststore secret name
        truststoreCaSecretName: [existing-secret-name-of-a-truststore-certificate]
        # -- Existing Truststore certificate name
        truststoreCaSecretCertName: [certificate-name-of-the-truststore-certificate]

    Be sure that the used keys are in PKCS#8 format and not in PKCS#1. You can be sure of this by checking the header of the key.

    It should ‘BEGIN PRIVATE KEY’ and not 'BEGIN RSA PRIVATE KEY'

More configuration can be found here

In case the resulted k8s resources collide with the existing resources, you the rest-proxy.fullnameOverride key to change the resource names

Schema-Registry

  1. Copy the existing platform.instance.schemaregistry section from the existing Instance’s values.yaml file and place it in the axual-streaming.axual-schema-registry section so that you can replace some keys.

    values.yaml 
    axual-streaming:
  axual-schema-registry:
    [existing-configuration at `platform.instance.schemaregistry`]

  2. Update the kafka section with some new configuration

    existing_values.yaml 
    axual-streaming:
  axual-schema-registry:
    kafka:
      external:
        address: true
        bootstrapServers: "SSL://[existing-bootstrap-url]:[existing-bootstrap-port]"
    new_values.yaml 
    axual-streaming:
  axual-schema-registry:
    # Kafka configuration
    kafka:
      # -- Kafka bootstrap servers
      bootstrapServers: "SSL://[existing-bootstrap-url]:[existing-bootstrap-port]"
      # -- Fully resolved name of topic used to store schemas (usually _{tenant}-{instance}-schemas)
      schemasTopic: [existing-schemas-topic]
      # -- Group prefix to give access to (usually {tenant}-{instance}-schema-registry-)
      groupPatternPrefix: [existing-schema-group-id]

  3. Replace registerAcls key with a new kafkaInitContainer key section

    existing_values.yaml 
    axual-streaming:
  axual-schema-registry:
    deploySchemasTopic:
      [existing-value]
    new_values.yaml 
    axual-streaming:
  axual-schema-registry:
    kafkaInitContainer:
      # -- Principal common name to give access to (should match tls.master.clientCertificatePem)
      masterPrincipal: [existing-schema-registry-master-client-full-chain-certificate]
      # -- Principal common name to give access to (should match tls.slave.clientCertificatePem)
      slavePrincipal: [existing-schema-registry-slave-client-full-chain-certificate]
      # -- (Optional) Principal common name used to produce and consume from schemas topic by Distributor
      # distributorPrincipal: ""
      # -- Replication factor of topic used to store schemas
      replicationFactor: [existing-replication-factor-of-schemas-topics]
      # -- min.isr of topic used to store schemas
      minIsr: [existing-min-in-sync-replicas-of-schemas-topics]
      tls:
        # -- Existing Keypair secret name
        keypairSecretName: [existing-secret-name-of-a-super-user-certificate]
        # -- Existing Keypair key name
        keypairSecretKeyName: [key-name-of-the-super-user-certificate]
        # -- Existing Keypair certificate name
        keypairSecretCertName: [certificate-name-of-the-super-user-certificate]
        # -- Existing Truststore secret name
        truststoreCaSecretName: [existing-secret-name-of-a-truststore-certificate]
        # -- Existing Truststore certificate name
        truststoreCaSecretCertName: [certificate-name-of-the-truststore-certificate]

    Be sure that the used keys are in PKCS#8 format and not in PKCS#1. You can be sure of this by checking the header of the key.

    It should ‘BEGIN PRIVATE KEY’ and not 'BEGIN RSA PRIVATE KEY'

  4. Add to the axual-schema-registry section a new configurationOverrides key.

    values.yaml 
    axual-streaming:
  axual-schema-registry:
    # Service and Service Annotations Configuration
    configurationOverrides:
      master:
        kafkastore.security.protocol: 'SSL'
        kafkastore.ssl.enabled.protocols: 'TLSv1.2'
        kafkastore.ssl.cipher.suites: ''
        ssl.cipher.suites: ''
        authentication.method: 'NONE'
        ssl.enabled.protocols: 'TLSv1.2'
        heap.opts: "-Xms512M -Xmx512M"
      slave:
        kafkastore.security.protocol: 'SSL'
        kafkastore.ssl.enabled.protocols: 'TLSv1.2'
        kafkastore.ssl.cipher.suites: ''
        ssl.cipher.suites: ''
        authentication.method: 'NONE'
        ssl.enabled.protocols: 'TLSv1.2'
        heap.opts: "-Xms512M -Xmx512M"
        ssl.client.auth: 'true'
        ssl.client.auth.need: 'true'

  5. Be sure that the networkPolicy key is present in the new axual-schema-registry.

    values.yaml 
    axual-streaming:
  axual-schema-registry:
    # Network policy configuration
    networkPolicy:
      podMatchLabels:
        app.kubernetes.io/name: "platform-manager"

More configuration can be found here

In case the resulted k8s resources collide with the existing resources, you the axual-schema-registry.fullnameOverride key to change the resource names

Verification

In this step, we are going to verify that the new Rest-Proxy and Schema-Registry can perform the same operation as the old components.

Port-Forward the Rest-Proxy service to your local machine and try to produce and consume with it.

Port-Forward the Schema-Registry Slave service to your local machine and try to access the /subjects endpoint. If you are able to see existing schemas, this proves that the new Schema-Registry can access the Kafka schemas topics.

If all checks are successful, you can proceed to the next steps.

Post Verification

Once verified that the new Schema-Registry works, before proceeding to the next step, you will have to update the Instance configuration in the Self-Service.

  1. Access the Self-Service

  2. Open the instances page

  3. Edit the instance you are migrating

  4. Remove the existing clusters (they will be added again with the updated Schema Registry details)

  5. Press Select Cluster

  6. Select the cluster used by this instance and provide the Schema Registry details

  7. Provide the updated Schema Registry Master service-name (e.g. http://[new-schema-registry-master-service-name:new-schema-registry-master-service-port])

  8. Select NoAUth as the authentication method

  9. Press the Verify button

  10. Press the Select Cluster button.

  11. Once inserted all the Clusters, press the Update Instance button.

Once the Instance is updated, verify that you can update an AVRO topic.

If you can update an AVRO topic, you can proceed to the next steps.

Switch Rest-Proxy and Schema-Registry ingress to new components

Objective

Redirect the existing Rest-Proxy and Schema-Registry Ingress(es) to the newly installed components.

Execution

Before proceeding with the re-direct of the Ingress(es) you need to be sure that either:

  • The newly installed applications are accepting unauthenticated traffic or

  • The Ingress(es) are correctly configured to authenticate against the applications

The configuration of the new Ingress(es) is very similar to the previous one. There are two differences:

  • host has been replaced with an array of hosts

  • For Schema-Registry, you can configure two Ingress(es), one for master and one for slave

Taking into account these differences you can copy and adapt the old installation configuration into the newly created values.yaml

Below, you can find and example of a final configuration of the Schema-Registry Ingress(es)

values.yaml 
axual-streaming:
  axual-schema-registry:
    ingress:
      slave:
          enabled: false
          # -- The name of the IngressClass cluster resource.
          className: [class-name]
          # -- Annotations to add to the Ingress resource.
          annotations: {}
          hosts:
            - # -- The fully qualified domain name of a network host.
              host: [host]
              paths:
                - # -- Matched against the path of an incoming request.
                  path: [path]
                  # -- Determines the interpretation of the Path matching.
                  # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
                  pathType: [path-type]
          # -- TLS configuration for this Ingress.
          tls:
            - secretName: [secret-name]
              hosts:
                - [host]
      master:
        # You can configure the master in the same way of the slave, if needed

And the configuration of the Rest-Proxy Ingress

values.yaml 
axual-streaming:
  rest-proxy:
    ingress:
      enabled: false
      # -- The name of the IngressClass cluster resource.
      className: [class-name]
      # -- Annotations to add to the Ingress resource.
      annotations: {}
      hosts:
        - # -- The fully qualified domain name of a network host.
          host: [host]
          paths:
            - # -- Matched against the path of an incoming request.
              path: [path]
              # -- Determines the interpretation of the Path matching.
              # Can be one of the following values: `Exact`, `Prefix`, `ImplementationSpecific`.
              pathType: [path-type]
      # -- TLS configuration for this Ingress.
      tls:
        - secretName: [secret-name]
          hosts:
            - [host]

Verification

In this step, we are going to verify that the new Rest-Proxy and Schema-Registry can be accessed using the same URLs that were being used for the old installation.

For Rest-Proxy, try to produce and consume using the URL defined in the Ingress.

For Schema-Registry, try to access the /subjects endpoint using the Ingress hostname. If you are able to see existing schemas, this proves that the new Schema-Registry can be accessed using the Ingress.