Connecting external box to cluster using kubectl

ℹ️ Preconditions:

1. kubectl installed.
2. Common version 3.9.1 and above.

---

⚠️ Please note that if external box has a pin with subscribe attribute and there is a box in kubernetes that publish on your pin (e.g. act has from_codec pin related to the queue in rabbitMQ and receives messages from codec), then, if you close your external application, the messages will be accumulated in the queue that can overfull the cluster memory. To prevent that please configure the queue limit on your external box pins. ⚠️

Example:

- name: from_codec
  connection-type: mq
  attributes:
    - first
    - oe
    - subscribe
    - parsed
  settings:
    storageOnDemand: false
    queueLength: 1000 

---

If you already have a kubectl configured and you do not need a service account, you can go directly to step 3

1. Get your service account token (you can find details in “How to create service account” on this page).

2. Configure kubernetes context using kubectl (you can find detailed information in kubernetes documentation)

   kubectl config set-credentials <service-account-name> --token=<token>
   kubectl config set-cluster <cluster-name> --server=https://5.6.7.8 --insecure-skip-tls-verify
   kubectl config set-context <context-name> --cluster=<cluster-name> --namespace=<namespace> --user=<service-account-name>
   

   Or change config file manually:

    apiVersion: v1
    clusters:
    - cluster:
        insecure-skip-tls-verify: true
        server: https://5.6.7.8
      name: <cluster-name>
    contexts:
    - context:
        cluster: <cluster-name>
        namespace: <namespace>
        user: <service-account-name>
      name: <context-name>
    current-context: "<context-name>"
    kind: Config
    preferences: {}
    users:
    - name: <service-account-name>
      user:
        token: <token>
   

3. Configure your box as external in CRs:

   externalBox - using this section we can configure boxes that are going to be run outside of kubernetes cluster. First of all we need to set enabled flag to true. Since the box is going to be run outside of kubernetes, we need to provide the address to that server using the address field. Finally in endpoints list, we specify internal mapping for ports, by giving name to the port and by providing its number as targetPort value. At the moment infrastructure processes only endpoint with the name ‘grpc’ and it affects how grpc.json will be configured for th2 components. List structure, and thus the ability to add other mappings besides ‘grpc' is contained there to support expansion and new functionalities in future releases.

   The simpliest way is to just add “externalBox: enabled: true” to an existing CR box. The full list of externalBox parameter can be found below:

   externalBox:
     enabled: true
     address: <e.g. IP>
     endpoints:
       - name: 'grpc'
         targetPort: 8080
   

4. Start your application with arguments (arguments for the CommonFactory):

   • --namespace < cluster namespace with declared externalBox >
   • --boxName < name of externalBox CR >
   • --contextName < context-name from step 2 >

   e.g.

   gradle run --args='--namespace myNamespace --boxName myExternalBox --contextName myContext'