Setting up Gateway API

Gateway API is a collection of API resources that model networking in a Kubernetes cluster.

In this tutorial, you will learn how to set up access to the applications deployed in two test environments, dev and prod, using Yandex Application Load Balancer via Gateway API. For this you will need to create a public domain zone and delegate the domain to Yandex Cloud DNS.

To integrate Gateway API and Application Load Balancer:

1. Create the Managed Service for Kubernetes resources.
2. Install Gateway API and set up the domain zones.
3. Prepare test applications.
4. Create test applications.
5. Test Gateway API.

If you no longer need the resources you created, delete them.

Required paid resourcesRequired paid resources

The support cost includes:

• Fee for a DNS zone and DNS requests (see Cloud DNS pricing).
• Fee for the Managed Service for Kubernetes cluster: using the master and outgoing traffic (see Managed Service for Kubernetes pricing).
• Cluster nodes (VM) fee: using computing resources, operating system, and storage (see Compute Cloud pricing).
• Fee for using the computing resources of the L7 load balancer (see Application Load Balancer pricing).
• Fee for public IP addresses (see Virtual Private Cloud pricing).

Getting startedGetting started

1. If you do not have the Yandex Cloud CLI yet, install and initialize it.

   The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

2. Register a public domain zone and delegate your domain.

Create the Managed Service for Kubernetes resourcesCreate the Managed Service for Kubernetes resources

1. Create a Kubernetes cluster and node group.

   Manually

   Terraform

   1. If you do not have a network yet, create one.

   2. If you do not have any subnets yet, create them in the availability zones where your Kubernetes cluster and node group will be created.

   3. Create security groups for the Managed Service for Kubernetes cluster and its node groups.

      Warning

      The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

   4. Create a Kubernetes cluster and a node group in any suitable configuration. When creating them, specify the security groups prepared earlier.

   1. If you do not have Terraform yet, install it.

   2. Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.

   3. Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it.

   4. Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.

   5. Download the k8s-gateway-api.tf cluster configuration file to the same working directory. This file describes:

      • Network.

      • Subnet.

      • Kubernetes cluster.

      • Service account required for the Kubernetes cluster and node group to operate.

      • Security groups which contain rules required for the Managed Service for Kubernetes cluster and its node groups.

        Warning

        The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

   6. Specify the following in the configuration file:

      • Folder ID.
      • Kubernetes version for the Kubernetes cluster and node groups.
      • Kubernetes cluster CIDR.

   7. Make sure the Terraform configuration files are correct using this command:

      terraform validate
      

      If there are any errors in the configuration files, Terraform will point them out.

   8. Create the required infrastructure:

      1. Run this command to view the planned changes:

         terraform plan
         

         If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

      2. If everything looks correct, apply the changes:

         1. Run this command:

            terraform apply
            

         2. Confirm updating the resources.

         3. Wait for the operation to complete.

      All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console.

2. Install kubect and configure it to work with the new cluster.

3. Create a service account required for Gateway API:

4. Assign the following roles to it:

   • alb.editor: To create the required resources.
   • certificate-manager.admin: To use certificates registered in Yandex Certificate Manager.
   • compute.viewer: To use Managed Service for Kubernetes cluster nodes in the load balancer target groups.
   • vpc.publicAdmin: To manage external connectivity.

5. Create a static key and save it to a file named sa-key.json:

   yc iam key create \
     --service-account-name <name_of_service_account_for_Gateway_API> \
     --output sa-key.json
   

Install Gateway API and set up the domain zonesInstall Gateway API and set up the domain zones

1. Install the Gateway API application according to the instructions. During the installation, use the service account key issued previously.

2. Reserve public IP addresses for the prod and dev test environments:

   yc vpc address create \
     --name=prod \
     --labels reserved=true \
     --external-ipv4 \
     zone=<availability_zone> && \
   yc vpc address create \
     --name=dev \
     --labels reserved=true \
     --external-ipv4 \
     zone=<availability_zone>
   

   Where <availability_zone> is the availability zone hosting your Kubernetes cluster.

   Save the public IP addresses: you will need them to continue the setup.

3. Add resource records for your public DNS zone:

   yc dns zone add-records \
     --name <DNS_zone_name> \
     --record '*.prod 60 A <prod_environment_IP_address>' && \
   yc dns zone add-records \
     --name <DNS_zone_name> \
     --record '*.dev 60 A <dev_environment_IP_address>'
   

   Example of a valid command:

   yc dns zone add-records \
    --name my-domain-name \
    --record '*.dev 60 A 171.154.241.41'
   

4. Create a namespace for TLS secrets:

   kubectl create namespace gateway-api-tls-secrets
   

5. Create OpenSSL certificates:

   openssl req -x509 \
     -newkey rsa:4096 \
     -keyout gateway-key-prod.pem \
     -out gateway-cert-prod.pem \
     -nodes \
     -days 365 \
     -subj '/CN=*.prod.<domain_zone>' && \
   openssl req -x509 \
      -newkey rsa:4096 \
      -keyout gateway-key-dev.pem \
      -out gateway-cert-dev.pem \
      -nodes \
      -days 365 \
      -subj '/CN=*.dev.<domain_zone>'
   

   Example of a valid command:

   openssl req -x509 \
    -newkey rsa:4096 \
    -keyout gateway-key-prod.pem \
    -out gateway-cert-prod.pem \
    -nodes \
    -days 365 \
    -subj '/CN=*.prod.my-test-domain.com'
   

   These certificates will be used to create secrets for the prod and dev test environments in the Kubernetes cluster.

6. Create the secrets:

   kubectl create -n gateway-api-tls-secrets secret tls gateway-prod-tls \
     --cert=gateway-cert-prod.pem \
     --key=gateway-key-prod.pem && \
   kubectl create -n gateway-api-tls-secrets secret tls gateway-dev-tls \
     --cert=gateway-cert-dev.pem \
     --key=gateway-key-dev.pem
   

Prepare test applicationsPrepare test applications

To test Gateway API, we will create two applications, tutum/hello-world and nginxdemos/hello. For each application, you will need to configure and run three YAML files:

• dev-gw.yaml and prod-gw.yaml with Gateway settings. In these manifest files, specify:
  • Security groups in which your Kubernetes cluster is deployed in the metadata.annotations.gateway.alb.yc.io/security-groups parameter.
  • Domain zone with the *.dev and *.prod prefixes in the hostname parameters.
  • IP addresses for the dev and prod environments in the spec.addresses.value parameter.
• dev-route.yaml and prod-route.yaml to configure routing for the applications. In these manifests, you need to specify the domain zone with the app.dev and app.prod prefixes in the spec.hostnames parameter.
• dev-app.yaml and prod-app.yaml with the applications’ settings. These manifests will be used to create:
  • Namespace (unique for each application)
  • Deployment for the application
  • Service

Configure the application for the dev environmentConfigure the application for the dev environment

1. Create a manifest named dev-gw.yaml:

   dev-gw.yaml

   ---
   apiVersion: gateway.networking.k8s.io/v1alpha2
   kind: Gateway
   metadata:
     name: gateway-api-dev
     annotations:
       gateway.alb.yc.io/security-groups: <cluster_security_group_IDs>
   spec:
     gatewayClassName: yc-df-class
     listeners:
     - name: gateway-api-dev
       protocol: HTTP
       port: 80
       hostname: "*.dev.<domain_zone>"
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchExpressions:
             - key: kubernetes.io/metadata.name
               operator: In
               values:
               - dev-app
     - name: gateway-api-dev-tls
       protocol: HTTPS
       port: 443
       hostname: "*.dev.<domain_zone>"
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchExpressions:
             - key: kubernetes.io/metadata.name
               operator: In
               values:
               - dev-app
       tls:
         certificateRefs:
         - group: ""
           kind: Secret
           name: gateway-dev-tls
           namespace: gateway-api-tls-secrets
         mode: Terminate
     addresses:
      - type: IPAddress
        value: "<dev_environment_IP_address>"
   

2. Create a file named dev-route.yaml:

   dev-route.yaml

   ---
   apiVersion: gateway.networking.k8s.io/v1alpha2
   kind: HTTPRoute
   metadata:
     name: dev-app-http-route
     namespace: dev-app
   spec:
     hostnames:
     - "app.dev.<domain_zone>"
     parentRefs:
     - name: gateway-api-dev
       namespace: default
     rules:
     - matches:
       - path:
           value: /
       backendRefs:
       - name: app
         port: 80
   

3. Create a manifest named dev-app.yaml:

   dev-app.yaml

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: dev-app
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: app
     namespace: dev-app
   spec:
     selector:
       matchLabels:
         app: app
     template:
       metadata:
         labels:
           app: app
       spec:
         containers:
         - name: app
           image: tutum/hello-world
           resources:
             limits:
               memory: "128Mi"
               cpu: "500m"
           ports:
           - containerPort: 80
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: app
     namespace: dev-app
   spec:
     type: NodePort
     selector:
       app: app
     ports:
     - port: 80
       targetPort: 80
   

Configure the application for the prod environmentConfigure the application for the prod environment

1. Create a manifest named prod-gw.yaml:

   prod-gw.yaml

   ---
   apiVersion: gateway.networking.k8s.io/v1alpha2
   kind: Gateway
   metadata:
     name: gateway-api-prod
     annotations:
       gateway.alb.yc.io/security-groups: <cluster_security_group_IDs>
   spec:
     gatewayClassName: yc-df-class
     listeners:
     - name: gateway-api-prod
       protocol: HTTP
       port: 80
       hostname: "*.prod.<domain_zone>"
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchExpressions:
             - key: kubernetes.io/metadata.name
               operator: In
               values:
               - prod-app
     - name: gateway-api-prod-tls
       protocol: HTTPS
       port: 443
       hostname: "*.prod.<domain_zone>"
       allowedRoutes:
         namespaces:
           from: Selector
           selector:
             matchExpressions:
             - key: kubernetes.io/metadata.name
               operator: In
               values:
               - prod-app
       tls:
         certificateRefs:
         - group: ""
           kind: Secret
           name: gateway-prod-tls
           namespace: gateway-api-tls-secrets
         mode: Terminate
     addresses:
       - type: IPAddress
         value: "<prod_environment_IP_address>"
   

2. Create a manifest named prod-route.yaml:

   prod-route.yaml

   ---
   apiVersion: gateway.networking.k8s.io/v1alpha2
   kind: HTTPRoute
   metadata:
     name: prod-app-http-route
     namespace: prod-app
   spec:
     hostnames:
     - "app.prod.<domain_zone>"
     parentRefs:
     - name: gateway-api-prod
       namespace: default
     rules:
     - matches:
       - path:
           value: /
       backendRefs:
       - name: app
         port: 80
   

3. Create a manifest named prod-app.yaml:

   prod-app.yaml

   ---
   apiVersion: v1
   kind: Namespace
   metadata:
     name: prod-app
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: app
     namespace: prod-app
   spec:
     selector:
       matchLabels:
         app: app
     template:
       metadata:
         labels:
           app: app
       spec:
         containers:
         - name: app
           image: tutum/hello-world
           resources:
             limits:
               memory: "128Mi"
               cpu: "500m"
           ports:
           - containerPort: 80
   ---
   apiVersion: v1
   kind: Service
   metadata:
     name: app
     namespace: prod-app
   spec:
     type: NodePort
     selector:
       app: app
     ports:
     - port: 80
       targetPort: 80
   

Create test applicationsCreate test applications

1. To install the applications, run this command:

   kubectl apply -f prod-gw.yaml && \
   kubectl apply -f prod-app.yaml && \
   kubectl apply -f prod-route.yaml && \
   kubectl apply -f dev-gw.yaml && \
   kubectl apply -f dev-app.yaml && \
   kubectl apply -f dev-route.yaml
   

2. Make sure the app pods have entered the Running state:

   kubectl get pods --namespace dev-app && \
   kubectl get pods --namespace prod-app
   

3. Make sure that a load balancer has been created for Gateway API:

   yc application-load-balancer load-balancer list
   

   Note

   It may take several minutes to create the load balancer.

Test Gateway APITest Gateway API

To test Gateway API, open these links in your browser:

• app.prod.<domain_zone>.
• app.dev.<domain_zone>.

Delete the resources you createdDelete the resources you created

Some resources are not free of charge. To avoid paying for them, delete the resources you no longer need: