F5 XC vk8s workload with Open Source Nginx

The nginx XC Distributed Cloud workload deployment for virtual kubernetes can be used for url regex rewrite, response body rewrite or advanced custom response pages.


I have shared the code in the link below under Devcentral code share:

F5 XC vk8s open source nginx deployment on RE | DevCentral


Here I will desribe the basic steps for creating a workload object that is F5 XC custom kubernetes object that creates in the background kubernetes deployments, pods and Cluster-IP type services. The free unprivileged nginx image nginxinc/docker-nginx-unprivileged: Unprivileged NGINX Dockerfiles (github.com)



  1. Create a virtual site that groups your Regional Edges and Customer Edges. After that create the vk8s virtual kubernetes and relate it to the virtual site."Note": Keep in mind for the limitations of kubernetes deployments on Regional Edges mentioned in Create Virtual K8s (vK8s) Object | F5 Distributed Cloud Tech Docs.


  2. First create the workload object and select type service that can be related to Regional Edge virtual site or Customer Edge virtual site.
  3. After select the container image that will be loaded from a public repository like github or private repo.
  4. You will need to configure advertise policy that will expose the pod/container with a kubernetes cluster-ip service. If you are deploying test containers, you will not need to advertise the container .
  5. To trigger commands at a container start, you may need to use /bin/bash -c -- and a argument."Note": This is not related for this workload deployment and it is just an example. 


  6. Select to overwrite the default config file for the opensource nginx unprivileged with a file mount. "Note": the volume name shouldn't have a dot as it will cause issues.
  7. For the image options select a repository with no rate limit as otherwise you will see the error under the the events for the pod. You can also configure command and parameters to push to the container that will run on boot up.
  8. You can use empty dir on the virtual kubernetes on the Regional Edges for volume mounts like the log directory or the Nginx Cache zone but the unprivileged Nginx by default exports the logs to the XC GUI, so there is no need. 

    "Note": This is not related for this workload deployment and it is just an example.

  9. The Logs and events can be seen under the pod dashboard and even the container/pod can accessed. "Note": For some workloads to see the logs from the XC GUI you will need to direct the output to stderr but not for nginx.
  10. After that you can reference the auto created kubernetes Cluster-IP service in a origin pool, using the workload name and the XC namespace (for example niki-nginx.default). 

    "Note": Use the same virtual-site where the workload was attached and the same port as in the advertise cluster config.


  11. Deployments and Cluster-IP services can be created directly without a workload but better use the workload option.
  12. When you modify the config of the nginx actually you are modifying a configmap that the XC workload has created in the background and mounted as volume in the deployment but you will need to trigger deployment recreation as of now not supported by the XC GUI. From the GUI you can scale the workload to 0 pod instances and then back to 1 but a better solution is to use kubectl.
  13. You can log into the virtual kubernetes like any other k8s environment using a cert and then you can run the command "kubectl rollout restart deployment/niki-nginx". Just download the SSL/TLS cert.


  14.  You can automate the entire process using XC API and then you can use normal kubernetes automation to run the restart command F5 Distributed Cloud Services API for ves.io.schema.views.workload | F5 Distributed Cloud API Docs!


Related resources:


For nginx Plus deployments for advanced functions like SAML or OpenID Connect (OIDC) or the advanced functions of the Nginx Plus dynamic modules like njs that is allowing java scripting (similar to F5 BIG-IP or BIG-IP Next TCL based iRules), see:


Enable SAML SP on F5 XC Application

Bolt-on Auth with NGINX Plus and F5 Distributed Cloud

Dynamic Modules | NGINX Documentation

njs scripting language (nginx.org)




Updated Jun 05, 2024
Version 2.0

Was this article helpful?

1 Comment

  • Nice article giving use case specifics around modifying the configuration parameters (configmap) within the XC UI, as this is super important navigating the security controls around not running containers/pods as privileged.