Optional Installation Step: Bring Your Own Certificate - Service Virtualization

Optionally, BlazeMeter can configure HTTPS connections to Service Virtualization over TLS/SSL. If your application requires a custom certificate to be able to communicate over HTTPS, please use the following steps to set up a custom certificate. After you have set this up, the virtual service response contains the identity information along with the response. The caller can then choose to trust it.

The communication is set up at the agent level. All virtual services deployed to this agent will use the custom certificate that has been set up for HTTPS. If you have additional certificate needs, install additional BlazeMeter agents.

Requirements

Minimum requirements to use HTTPS:

  • X509 compatible public certificate in PEM format
  • Base64 encoded private key in PEM format with PKCS#8 syntax
  • BlazeMeter agent installed as a Docker or Kubernetes agent.

In addition to configuring your own certificate for your virtual services to use, it is important to configure a hostname override on the agent. The override is needed so that the Asset Catalog can generate endpoint URLs to access virtual services using the combination of hostname and port, instead of using a combination of IP address and port.

The process is different depending on whether you use a Docker or a Kubernetes agent.

  1. Client-Side Hostname Validation for a Docker Agent
  2. Configure Certificate and Hostname in a Docker Agent
  3. Client-Side Hostname Validation for a Kubernetes Agent
  4. Configure Certificate in a Kubernetes Agent

Client-Side Hostname Validation for a Docker Agent

In order for hostname validation to work in most HTTPS clients, the hostname of the request has to match one of the following pieces of information in the TLS certificate that is served by the virtual service:

  • One of the DNSName entries in the Subject Alternative Name (SAN) extension
  • Common Name (CN) field of the owner Subject

Example: When using a certificate that has *.example.com set in either its SAN extension or CN subject field, any request to a subdomain of example.com passes hostname validation.

Configure Certificate and Hostname in a Docker Agent

Follow these steps:

  1. Follow the same process as for installing an agent as described in Install a BlazeMeter Agent (Docker), but stop once you have generated the Docker run command.
  2. Copy the docker run command and add the following environment variables and volume to the docker run command.
    The bold portion below is the only part that can change
    --env TLS_CERT=/etc/ssl/certs/public.pem
    --env TLS_KEY=/etc/ssl/certs/privatekey.pem
    -v /path/to/public.pem:/etc/ssl/certs/public.pem
    -v /path/to/privatekey.pem:/etc/ssl/certs/privatekey.pem
  3. Configure the hostname so that the Asset Catalog can generate endpoint URLs to access virtual services using the combination of hostname and port instead of using a combination of IP address and port. 
    --env HOSTNAME_OVERRIDE=C123ABCXYZ
  4. Verify that the final full Docker run command (all on one line) looks like the following example: 
    docker run -d --env TLS_CERT=/etc/ssl/certs/public.pem 
                  --env TLS_KEY=/etc/ssl/certs/privatekey.pem 
                  --env HARBOR_ID=<Harbor ID> --env SHIP_ID=<Ship ID> 
                  --env AUTH_TOKEN=<Auth Token> 
                  --env AUTO_UPDATE=true --env DISTRIBUTION=stable 
                  --env HOSTNAME_OVERRIDE=C123ABCXYZ 
                  --name=blazemeter-crane 
                  --restart=on-failure 
                  -v /path/to/public.pem:/etc/ssl/certs/public.pem 
                  -v /path/to/privatekey.pem:/etc/ssl/certs/privatekey.pem     
                  -v /var/run/docker.sock:/var/run/docker.sock 
                  -v /tmp:/tmp --net=host blazemeter/crane python agent/agent.py
  5. If you have other settings to add, for example your proxy setup, define those variables as well.
  6. Once you have added the extra values, copy the edited command, and paste and run it in a terminal on the machine where you are installing your Agent.
  7. Follow the final steps of the Agent installation article to complete the installation.

Client-Side Hostname Validation for a Kubernetes Agent

Kubernetes based agents return a DNS based URL that you can use for accessing the virtual service. As an end-user, you do not have to set a hostname override for a Kubernetes agent.

Configure Certificate in a Kubernetes Agent

To set up certificates in a Kubernetes based agent, follow these steps:

  1. Install an Ingress Controller
  2. Create the kubectl secret for your custom certificate and private key
  3. Install the agent on Kubernetes

Install an Ingress Controller

When running in a Kubernetes cluster, the agent creates Ingress resources to allow external access to virtual services. In order for the Ingress resource to work, the cluster must have an Ingress Controller installed and running.

If you already have an Ingress Controller installed, you can skip the following sections and continue with the Create the kubectl secret step.

Example: How to install nginx-ingress Ingress Controller as LoadBalancer Service

If you would like to use an nginx-ingress Ingress Controller with a load balancer, but your Kubernetes cluster runs on a bare metal cluster and does not support an external load balancer, you can install a software load balancer such as MetalLB into your cluster. Refer to the nginx-ingress documentation on MetalLB and other options for bare metal clusters here: https://kubernetes.github.io/ingress-nginx/deploy/baremetal/

If your Kubernetes cluster is hosted on a cloud provider like GCP or AWS, then an external load balancer is provided and there is no need for MetalLB.

You can use any form of installation mentioned in https://docs.nginx.com/nginx-ingress-controller/installation/, but make sure you set the additional parameters that are part of ingress-config.yaml. The below steps use helm to install nginx-ingress.

The default ssl certificate maps to a secret named “crane-tls” under the default namespace. This secret’s installation will be covered in the Create the kubectl secret step.

Follow these steps:

  1. Create a new yaml file, name it ingress-config.yaml, and enter the following content:

    controller:
      publishService:
        enabled:true
      extraArgs:
        default-ssl-certificate: "default/crane-tls"
      config:
        enable-underscores-in-headers: "true"
        ssl-redirect: "false"
      rbac:
        create: true
      defaultBackend:
        service:
          loadBalancerIP: <your_load_balancer_IP>
  2. When using an external load balancer to allow access to the nginx-ingress controller, you can set the loadBalancerIP value to its IP address.
  3. To view the different versions of nginx-ingress available, enter the following command in your terminal: 
    helm search repo nginx-ingress
  4. To use the stable version, enter the following command: 
    helm install nginx-ingress stable/nginx-ingress -f ingress-config.yaml -n default
  5. To verify the installation, enter: 
    kubectl get all
    If you see “Pending” under the External-IP column for the ingress controller service, it is an indication that ingress is still trying to get an external IP.

Once the controller and backend pods are in 'Running' status, proceed with the Create the kubectl secret step.

Example - Installing nginx-ingress Ingress Controller as a NodePort Service

The default ssl certificate maps to a secret named “crane-tls” under default namespace. This secret’s installation is covered in the Create the kubectl secret step.

You can use any form of installation mentioned in https://docs.nginx.com/nginx-ingress-controller/installation/, but make sure you set the additional parameters that are part of ingress-config.yaml. The below steps are going to use helm to install nginx-ingress.

Follow these steps:

  1. Create a new yaml file, name it ingress-config.yaml and enter the following content to that file. 
    controller:
      publishService:
        enabled:true
      extraArgs:
        default-ssl-certificate: "default/crane-tls"
      config:
        enable-underscores-in-headers: "true"
        ssl-redirect: "false"
    rbac:
      create: true
    defaultBackend:
      service:
        type: NodePort
  2. To find the different versions of nginx-ingress available, enter the following command in your terminal: 
    helm search repo nginx-ingress
  3. To use the stable version, enter the following command: 
    helm install nginx-ingress stable/nginx-ingress -f ingress-config.yaml -n default
  4. Verify that the External-IP column for the ingress controller service is 127.0.0.0, and the backend’s service type is ‘NodePort’. To verify the installation, enter the following command: 
    kubectl get all

Once the controller and backend pods are in Running status, proceed to the Create the kubectl secret Step.

Create the kubectl secret for your custom certificate and private key

Follow these steps:

  1. Create a new secret in Kubernetes with your custom certificate and private key.
  2. Name the secret ‘crane-tls’. The kubectl command for creating a secret is: 
    kubectl create secret tls crane-tls --key ${KEY_FILE} --cert ${CERT_FILE}
  3. If you choose to use a different name for the secret or to use an existing secret, update this value in the ingress yaml file that is mentioned in the Install an Ingress Controller step.

This kubectl command creates a new secret under the default namespace. You are good to proceed to the next step where we install the agent on the Kubernetes.

Install the agent on Kubernetes

Follow these steps:

    1. Follow the steps mentioned in the Kubernetes installation guide at Optional Installation Step: Manual Kubernetes Agent Installation), but stop right before you run the following command: 
      kubectl apply -f ${deploymentFileName} (i.e. dpl-crane.yaml) in step #7
    2. Add the following new environment variables to the existing list in the deployment file (i.e. dpl-crane.yaml) 
      - name: KUBERNETES_WEB_EXPOSE_TYPE
        value: INGRESS
      - name: KUBERNETES_WEB_EXPOSE_SUB_DOMAIN
        value: crane.blazemeter.net
      - name: KUBERNETES_WEB_EXPOSE_TLS_SECRET_NAME
        value: crane-tls
    3. Ensure that the certificate configured in the TLS secret in the Create the kubectl secret step matches requests to any sub-domain of the value mentioned in KUBERNETES_WEB_EXPOSE_SUB_DOMAIN.
    4. Set the environment variable KUBERNETES_WEB_EXPOSE_TLS_SECRET_NAME to the secret created in the Create the kubectl secret step.

Now you can deploy and run the pod.

  1. Execute the following kubectl command to deploy your deployment file (i.e. dpl-crane.yaml): 
    kubectl apply -f deploymentFilename
  2. View the status of your pods. 
    kubectl get all
  3. Add an entry in your /etc/hosts file for the KUBERNETES_WEB_EXPOSE_SUB_DOMAIN environment variable value that you have set (in our example, crane.blazemeter.net), and map it to your localhost or 127.0.0.1.

Once you see that the crane pod status is "Running", return back to Step#9 of the Kubernetes installation page at Optional Installation Step: Manual Kubernetes Agent Installation to complete the installation.