Getting Started

Install the Gateway Controller & create an EPIC gateway

This Getting Started Guide provides the steps required to add a Gateway to an application in your Kubernetes Cluster.

These instructions setup access to a simple test application. Once configured, the test application is exposed using a DNS name derived from the Gateway template, in this case using the service name and other account information. The instructions are broken into three steps:

  1. System Administrator. Install & Configure the Gateway Controller
  2. Developer. Install Application (optional)
  3. Developer. Create Gateway & application routes

Let’s get started….

Prerequisites

  • Kubernetes cluster. The cluster can be provisioned by a Cloud provider or locally provisioned. The Gateway Controller uses IPv4 to communicate with the EPIC Gateway. At the moment we support only IPv4 or dual-stack clusters, IPv6-only clusters are not supported. The Gateway controller does not support ARM hosts at this time. There are no other specific cluster requirements.

  • Active account on the EPIC Gateway Service. An active account will provide the information needed to configure the Gateway Controller.

Getting an EPIC account.

Creating an EPIC account is simple, navigate to gwsm.acnodal.io

Your account is created by logging in with your GitHub Account (the magic of OAuth). By default your account will be populated with Gateway templates that provision an IPv6 external or downstream address. The k8s cluster remains IPv4. If you need an IPv4 address please let us now at trial@acnodal.io and we update your templates.

Install the Gateway Controller

Next install the Gateway Controller on your Kubernetes cluster. This is a simple two step process.

  1. Install k8s Gateway-SIG Custom Resource Definitions. The Gateway API is under active development. In time it will be added by default to all k8s installations, however currently it’s necessary to add the Gateway definitions manually. We don’t bundle this with the installation of the EPIC Gateway Controller as that is not recommended by the Gateway-SIG and in the future we won’t need to do it. The complete installation instructions are at kubernetes-sigs/gateway-api.
kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v0.4.0" \
| kubectl apply -f -
  1. Install the Gateway Controller. The Gateway Controller is installed from a manifest (Helm charts will be available soon).

The Gateway Controller is downloaded from our Gitlab repo. The installation yaml is located in the Package Registry. Samples are also located in this repo.

kubectl apply -f https://gitlab.com/api/v4/projects/acnodal%2Fpublic/packages/generic/manifest/v0.17.1/epic-gateway.yaml

Configure the Gateway Controller

As soon as your EPIC account has been activated the Gateway Controller can be configured. The EPIC Gateway Service Manager contains all of the information necessary to configure the Gateway Controller. Our Gitlab repo contains the samples used in this guide.

  1. Create the GatewayClassConfig. The GatewayClassConfig contains the information necessary to create gateways. For simplicity, apply the template GatewayClassConfig first and then edit
kubectl apply -f https://gitlab.com/api/v4/projects/34809193/repository/files/gatewayclassconfig.yaml/raw
  1. Edit the sample GatewayClassConfig. The sample is named uswest-gatewayhttp in the epic-gateway namespace.
kubectl edit -n epic-gateway gatewayclassconfig uswest-gatewayhttp
  1. Navigate to the Gateway Service Manager - gwsm.acnodal.io.

  1. Create a Service Account. Select the Service-Account Manage button from the Gateway Access Information.

Add a service account and service key for use in the GatewayClassConfig.

  1. Update the GatewayClassConfig to match EPIC parameters.
EPIC GatewayClassConfig Comments
Cluster cluster-name cluster name displayed in the Gateway Service Manager
gateway-hostname gateway-hostname the Region name
gateway Template gateway-template template used to create the gateway
service Account service-account created in previous step
service Key service-key created in previous step
User-Namespace user-namespace your namespace in the region

  1. Create a GatewayClass. The GatewayClass provides a binding between gateways and the gatewayclass config.
kubectl apply -f https://gitlab.com/api/v4/projects/34809193/repository/files/gatewayclass.yaml/raw
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: GatewayClass
metadata:
  name: uswest-gatewayhttp
spec:
  controllerName: acnodal.io/epic
  parametersRef:
    name: uswest-gatewayhttp
    namespace: epic-gateway
    group: puregw.acnodal.io
    kind: GatewayClassConfig

Congratulations! This completes the system administration component. Gateways can now be created.

Install a sample Application (optional)

Acnodal has created a small test webserver that can be deployed on your cluster. It returns information about the request, the cluster and the configuration of services.

Create a namespace for the demonstration application

kubectl create namespace gtw-test

Install the Application

kubectl apply -f https://gitlab.com/api/v4/projects/34868073/repository/files/deploy%2Fepic-echoserver.yaml/raw

Create the Service

kubectl apply -f https://gitlab.com/api/v4/projects/34868073/repository/files/deploy%2Fepic-echoserver-service.yaml/raw

The test webserver is available at gitlab.

Create a Gateway & Routes

  1. Create the Gateway. The Gateway references the gatewayclass previously created. Multiple gateways can be created from a gatewayclass/gatewayclassconfig. Create the gateway in the same namespace as the application; by default a gateway will be accessible by routes in the same namespace.

Apply the following yaml.

kubectl apply -f https://gitlab.com/api/v4/projects/34809193/repository/files/gateway.yaml/raw
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: Gateway
metadata:
  name: uswest-demows
spec:
  gatewayClassName: uswest-gatewayhttp
  listeners:
  - protocol: HTTP
    port: 80
    name: epic-demows

Check that the gateway is created, an address should be allocated.

$ kubectl get gateway
NAME          CLASS                ADDRESS       READY   AGE
uswest-demows uswest-gatewayhttp   72.52.66.60   True    3m6s
  1. Create HTTPRoutes

Routes provide the glue between gateways and services. Routes can reference multiple gateways and services and can be contained in multiple definitions.

spec description
parentRefs refers to Gateways
backendRefs refers to Services

Apply the following yaml.

kubectl apply -f https://gitlab.com/api/v4/projects/34809193/repository/files/httproute.yaml/raw
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  name: uswest-demows
spec:
  parentRefs:
  - name: uswest-demows
    namespace: gtw-test
  rules:
  - backendRefs:
    - name: epic-demows
      namespace: gtw-test
      port: 8080

Inspect the route status.

adamd@purelb1:~$ k get httproutes uswest-demows -o yaml
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: HTTPRoute
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
            {"apiVersion":"gateway.networking.k8s.io/v1alpha2","kind":"HTTPRoute","metadata":{"annotations":{},"name":"uswest-demows","namespace":"gtw-test"},"spec":{"parentRefs":[{"name":"uswest-gatewayhttp","namespace":"gtw-test"}],"rules":[{"backendRefs":[{"name":"epic-demows","namespace":"gtw-test","port":8080}]}]}}
  creationTimestamp: "2022-03-28T20:45:20Z"
  generation: 1
  name: uswest-demows
  namespace: gtw-test
  resourceVersion: "1404426"
  selfLink: /apis/gateway.networking.k8s.io/v1alpha2/namespaces/gtw-test/httproutes/uswest-demows
  uid: 68c00477-2861-40ec-8ac0-5e7e5cfd83d1
spec:
  parentRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: uswest-gatewayhttp
    namespace: gtw-test
  rules:
  - backendRefs:
    - group: ""
      kind: Service
      name: epic-demows
      namespace: gtw-test
      port: 8080
      weight: 1
    matches:
    - path:
        type: PathPrefix
        value: /

Congratulations - Your Gateway is now created.

Check Operation

The gateway is now created and if the demonstration application was used, it should be possible to connect to the application using either the IP address or DNS name. Note that we created a nonsecure application using port 80, if you used the TLS gateway template, connection will require use of the DNS name.

The address and DNS information can be found at the Gateway Service Manager; selecting the gateway from the main screen will show the configuration of the gateway, endpoint and envoy configurations.

In this case, the ip address is 72.52.66.48 and the url is http://uswest-demows.gtw-test.epictest.uswest.epick8sgw.net

The demonstration application shows addressing, gateway and service information, matching the Gateway Service Manager and the cluster configuration. Take note as to how all of the information is referenced making it easy to identify how requests are forwarded to gateways.

Thanks for trying EPIC More examples are available at the Kubernetes Gateway-API Getting Started guide.