Add HTTPRoute Template To Stirling-PDF Chart: A Guide

Nov 18, 2025 by Alex Johnson 54 views

Add HTTPRoute Template to Stirling-PDF Chart: A Comprehensive Guide

Adding an HTTPRoute template to your Stirling-PDF chart can significantly enhance its functionality and adaptability, especially as the Kubernetes ecosystem evolves. This comprehensive guide will walk you through the process, explain the benefits, and ensure you understand why this addition is becoming increasingly crucial. Let's dive in!

Understanding HTTPRoute and Gateway API

In the realm of Kubernetes, HTTPRoute is a resource defined within the Gateway API, a modern alternative to the traditional Ingress resource. The Gateway API offers more flexibility and advanced features, making it a compelling choice for managing external access to your applications. Think of it as the next-generation Ingress, designed to address the limitations and complexities of its predecessor. The Gateway API is designed to be more expressive and role-oriented, allowing different teams within an organization to manage different aspects of the gateway configuration. This is a significant improvement over the Ingress API, which often requires cluster administrators to manage all aspects of the configuration.

Why is HTTPRoute Needed?

The Kubernetes landscape is shifting, with the Gateway API gradually replacing Ingress as the preferred method for managing external access. One of the primary drivers behind this shift is the deprecation of ingress-nginx, a popular Ingress controller. This deprecation has prompted many users to explore alternatives, and the Gateway API has emerged as a robust and feature-rich solution. By adding an HTTPRoute template to the Stirling-PDF chart, you future-proof your deployment and align with the evolving standards of the Kubernetes community. This ensures that your application can seamlessly transition to newer technologies and take advantage of the advanced capabilities offered by the Gateway API.

Furthermore, HTTPRoute provides more granular control over traffic routing, allowing you to define complex routing rules based on headers, paths, and other criteria. This level of control is essential for modern applications that require sophisticated traffic management capabilities. For instance, you can use HTTPRoute to implement canary deployments, A/B testing, and other advanced deployment strategies.

Key Benefits of Using HTTPRoute

Enhanced Flexibility: HTTPRoute offers more flexible traffic routing options compared to Ingress. You can define rules based on various criteria, including headers and paths.
Improved Scalability: The Gateway API is designed to handle complex routing scenarios, making it suitable for large-scale deployments.
Role-Oriented Design: The Gateway API's role-oriented design allows different teams to manage different parts of the gateway configuration, improving collaboration and reducing bottlenecks.
Future-Proofing: By adopting HTTPRoute, you're aligning with the future direction of Kubernetes networking.

Step-by-Step Guide to Adding HTTPRoute Template

To add an HTTPRoute template to the Stirling-PDF chart, you'll need to follow a series of steps. This process involves creating the template file, configuring the chart, and ensuring that the necessary prerequisites are met. Let's break down each step in detail.

1. Prerequisites: Installing Gateway API CRDs

Before you can use HTTPRoute, you need to ensure that the Gateway API Custom Resource Definitions (CRDs) are installed in your Kubernetes cluster. CRDs extend the Kubernetes API, allowing you to define custom resources like HTTPRoute. These CRDs are not included in the core Kubernetes installation, so you'll need to install them separately. This is a crucial step, as attempting to create an HTTPRoute without the CRDs will result in errors.

To install the Gateway API CRDs, you can use kubectl, the Kubernetes command-line tool. The following command will apply the necessary CRDs to your cluster:

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v0.6.2/standard-install.yaml

This command fetches the CRD definitions from the official Gateway API repository on GitHub and applies them to your cluster. Make sure you have kubectl configured to connect to your Kubernetes cluster before running this command. You can verify the installation by checking for the Gateway API resources in your cluster:

kubectl get crds | grep gateway.networking.k8s.io

This command will list the Custom Resource Definitions related to the Gateway API, confirming that they have been successfully installed.

2. Creating the HTTPRoute Template File

The next step is to create the HTTPRoute template file. This file will define the HTTPRoute resource that you want to deploy with your Stirling-PDF chart. The template file is typically written in YAML and should include the necessary specifications for your routing requirements. Here's an example of a basic HTTPRoute template:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: stirling-pdf-httproute
spec:
  parentRefs:
    - name: stirling-pdf-gateway
  hostnames:
    - "stirling-pdf.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: stirling-pdf-service
          port: 80

Let's break down this template:

apiVersion: Specifies the API version for the HTTPRoute resource. In this case, it's gateway.networking.k8s.io/v1beta1.
kind: Defines the type of resource, which is HTTPRoute.
metadata.name: Sets the name of the HTTPRoute resource, here it's stirling-pdf-httproute.
spec.parentRefs: References the Gateway resource that this HTTPRoute will be attached to. The name field specifies the name of the Gateway.
spec.hostnames: Defines the hostnames that this HTTPRoute will handle. In this example, it's stirling-pdf.example.com.
spec.rules: Specifies the routing rules. Each rule consists of matches and backendRefs.
- matches: Defines the criteria for matching incoming requests. In this case, it matches all paths (/) using PathPrefix.
- backendRefs: Specifies the backend service to which the traffic should be routed. The name field specifies the name of the service, and the port field specifies the port number.

Save this template in a file, for example, httproute.yaml, within your chart's directory.

3. Configuring the Stirling-PDF Chart

Now, you need to configure the Stirling-PDF chart to include the HTTPRoute template. This typically involves modifying the chart's values.yaml file and adding the template to the chart's templates directory. The values.yaml file is where you define the default configuration values for your chart, and the templates directory contains the YAML files that define the Kubernetes resources.

Modify `values.yaml`

Open the values.yaml file in your Stirling-PDF chart and add the following configuration options:

httpRoute:
  enabled: false
  hostname: "stirling-pdf.example.com"
  gatewayName: "stirling-pdf-gateway"

These options allow you to control whether the HTTPRoute is enabled, the hostname for the HTTPRoute, and the name of the Gateway resource. The enabled option is set to false by default, making the HTTPRoute optional. This is important because the Gateway API CRDs may not be installed in all environments.

Add the Template to the Chart

Create a new file named httproute.yaml in the templates directory of your chart. Copy the content of the HTTPRoute template you created in step 2 into this file. Next, you'll use Helm templating to make the HTTPRoute configurable. Modify the httproute.yaml file as follows:

{{- if .Values.httpRoute.enabled }}
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: {{ .Release.Name }}-httproute
spec:
  parentRefs:
    - name: {{ .Values.httpRoute.gatewayName }}
  hostnames:
    - "{{ .Values.httpRoute.hostname }}"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: {{ .Release.Name }}-stirling-pdf-service
          port: 80
{{- end }}

The {{- if .Values.httpRoute.enabled }} and {{- end }} directives ensure that the HTTPRoute is only created if the httpRoute.enabled option is set to true in values.yaml. The {{ .Release.Name }} and {{ .Values.httpRoute.gatewayName }} are Helm template functions that substitute the release name and gateway name, respectively.

4. Deploying the Chart with HTTPRoute

With the template and configuration in place, you can now deploy the Stirling-PDF chart with the HTTPRoute. To enable the HTTPRoute, you need to set the httpRoute.enabled option to true when deploying the chart. You can do this using the --set flag with the helm install command:

helm install stirling-pdf ./stirling-pdf-chart --set httpRoute.enabled=true

Replace stirling-pdf with the desired release name and ./stirling-pdf-chart with the path to your chart directory. This command will deploy the chart and create the HTTPRoute resource in your Kubernetes cluster.

5. Verifying the HTTPRoute

After deploying the chart, you should verify that the HTTPRoute has been created successfully. You can do this using kubectl:

kubectl get httproute

This command will list all the HTTPRoute resources in your cluster. You should see the stirling-pdf-httproute (or the name you specified in the template) in the list. To get more details about the HTTPRoute, you can use the describe command:

kubectl describe httproute stirling-pdf-httproute

This command will show the configuration of the HTTPRoute, including the hostnames, rules, and backend references. Check the output to ensure that the HTTPRoute is configured correctly and pointing to the appropriate service.

Making HTTPRoute Optional

One crucial aspect of adding an HTTPRoute template is ensuring that it remains optional. This is because the Gateway API CRDs are not included in core Kubernetes and must be installed separately. If you try to create an HTTPRoute without the CRDs, the deployment will fail. By making the HTTPRoute optional, you allow users who haven't installed the CRDs to still deploy the chart without issues. This is why the httpRoute.enabled option in values.yaml is set to false by default.

Why Optionality Matters

Compatibility: Not all Kubernetes clusters have the Gateway API CRDs installed. Making the HTTPRoute optional ensures that the chart can be deployed in a wider range of environments.
Flexibility: Users can choose whether to enable the HTTPRoute based on their specific requirements and infrastructure.
Error Prevention: By default, disabling the HTTPRoute prevents deployment failures in environments without the CRDs.

Implementing Optionality

The key to making the HTTPRoute optional is the {{- if .Values.httpRoute.enabled }} directive in the httproute.yaml template. This directive tells Helm to only include the HTTPRoute resource in the deployment if the httpRoute.enabled option is set to true. If the option is false (or not set), the HTTPRoute resource will not be created.

This approach ensures that the chart can be deployed successfully in any Kubernetes cluster, regardless of whether the Gateway API CRDs are installed. Users who want to take advantage of the HTTPRoute can simply enable it by setting the httpRoute.enabled option to true during deployment.

Conclusion

Adding an HTTPRoute template to the Stirling-PDF chart is a forward-looking step that aligns with the evolving Kubernetes ecosystem. By leveraging the Gateway API, you can enhance the flexibility, scalability, and control over your application's traffic routing. This guide has provided a detailed walkthrough of the process, from installing the necessary CRDs to configuring the chart and deploying the HTTPRoute. Remember to keep the HTTPRoute optional to ensure compatibility across different Kubernetes environments.

By following these steps, you can seamlessly integrate HTTPRoute into your Stirling-PDF deployment and take advantage of the advanced features offered by the Gateway API. This not only future-proofs your application but also provides a more robust and flexible solution for managing external access.

For further reading on Kubernetes Gateway API, you can check out the official documentation at Gateway API Official Documentation. This resource provides in-depth information on the concepts, architecture, and usage of the Gateway API, helping you to deepen your understanding and effectively utilize its capabilities.