Skip to content

Getting Started#

In this guide, you will complete the following objectives:

  • Deploy an application on the platform, complete with an HTTPS endpoint
  • Use Headlamp to view logs and pod details

Deploying a Simple Application#

There are several steps required to deploy an application and have it be accessible via HTTPS. Specifically, we need to define the application itself, expose it on the cluster network, request a TLS certificate, and define HTTP routing rules. While this sounds complicated, it's fairly simple. Let's get started!

Defining the Application#

In your tenant manifest repo, create a file named deployment.yaml with the following YAML. What this is doing is defining a simple application named hello-world which will use a container image we developed for the PilotFest workshop. This definition is also setting resource requests and limits, which is a good practice to help ensure that both your app gets the resources it needs and it doesn't affect others. We'll also see a liveness probe, which tells us if the application is healthy and is useful when rolling out new updates.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-world
spec:
  selector:
    matchLabels:
      app: hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      containers:
        - name: hello-world
          image: code.vt.edu:5005/it-common-platform/tenant-support/images/pilotfest-2021/first-image:latest
          ports:
            - name: http
              containerPort: 3000
          resources:
            requests:
              memory: 32Mi
              cpu: 50m
            limits:
              memory: 128Mi
              cpu: 500m
          livenessProbe:
            httpGet:
              path: /
              port: 3000

Once you've committed this file, you should see the manifest be applied and a pod startup in Headlamp. Note that the pod name may not exactly match what you see in the sample screenshot.

Requesting a TLS Certificate#

Now that we have a containerized application, let's start the process to expose it. The first thing we'll do is request a TLS certificate. For a domain name, all tenants are authorized to use *.<tenant-id>.tenants.platform.it.vt.edu. For this guide, we'll simply use the root of your tenant domain. But, you can create a subdomain if you'd like.

In your tenant repo, create a file named certificate.yaml with the following YAML. Be sure to replace my-tenant-name in both commonName and dnsNames with your tenant identifier. What this will do is request a TLS certificate for the specified names and store the private key and certificate into a Kubernetes secret named hello-world-tls-cert.

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: hello-world
spec:
  commonName: my-tenant-name.tenants.platform.it.vt.edu
  dnsNames:
    - my-tenant-name.tenants.platform.it.vt.edu
  secretName: hello-world-tls-cert
  issuerRef:
    kind: ClusterIssuer
    name: letsencrypt

After defining the manifest, you'll probably see a few things happen in Headlamp. Since we are currently using LetsEncrypt to issue certificates, you will see a temporary pod and domain/ingress defined in your namespace to complete the HTTP challenge. Once the challenge is completed and the certificate is issued, you'll see it all disappear and you'll be left with a Certificate in the "Ready" state.

Defining the HTTP Routing Config#

Now that we have a certificate defined, let's define our HTTP routing configuration. To keep it simple, we're going to send all requests for our domain to our application. The cluster routing components don't search for pods directly, but use "Services" to discover the application (more on that in the next step).

Create a file named ingress.yaml with the following YAML. This will define a routing rule that will send all requests to our tenant domain to a Service named hello-world, which we'll define in the next step. Be sure to replace my-tenant-name in both the host and tls.hosts fields with your tenant identifier. This also provides config to routing components to use the TLS key/cert stored in hello-world-tls-cert (which the Certificate defines and components will populate).

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: hello-world
spec:
  rules:
    - host: my-tenant-name.tenants.platform.it.vt.edu
      http:
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: hello-world
              port: 
                number: 3000
  tls:
  - hosts:
      - my-tenant-name.tenants.platform.it.vt.edu
    secretName: hello-world-tls-cert

Once this is defined, you should now see a listing in the "Your Domains" card, but no pods are connected to that ingress. As mentioned earlier, that's because we don't have the Service defined yet.

Exposing the Application on the Cluster Network#

Now, all we need to do is define a Service, which exposes the container on the cluster network. This will finally allow the pod to be discovered by the HTTP routing components.

In a file named service.yaml, place the following YAML to define the Service. What this is going to do is expose all pods that have a label with key app and value hello-world (which our Deployment defines).

apiVersion: v1
kind: Service
metadata:
  name: hello-world
spec:
  selector:
    app: hello-world
  ports:
    - port: 3000

Once the manifest is applied, you should see the domain card be updated to indicate there is a pod that services the ingress. In addition, you'll see a "Open URL" link that allows you to quickly open the webpage. Open it up and you should see a simple "Todo App". Congrats! 🎉

Using Headlamp#

Although we've used Headlamp a few times already, there are a few other neat capabilities that you might find useful.

Viewing Pod Details and Logs#

If you click on the link for a specific pod, you will see quite a few details about the pod, including environment variables, volume information, and resource utilization.

Using kubectl#

While Headlamp provides a lot of insights, it doesn't expose everything. Kubectl is a Kubernetes command-line tool that can be configured to query resources, read logs, and more.

  1. If you don't already have kubectl (it's installed with Docker Desktop), follow these instructions to install kubectl.

  2. After logging into Headlamp, click on "Get Token" in the sidebar. You'll want to click "COPY ALL" the first time you are setting things up and paste it into your terminal. Subsequently, you only need to use "COPY CONTEXT AND TOKEN".

  3. Try to query the running pods and see if our hello world app is up and running:

    kubectl get pods

Third-Party Integration and Support

The config is stored in ~/.kube/config and is typically referred to as a "kubeconfig" file. Many other third-party tools can use this file to visualize and help you see what's going on with the cluster (for the resources you can see). You are welcome to explore them, but be mindful of procurement practices and who might have access to your config, as your credential is stored there.

Next Steps#

Now that you have a simple app up and running, it's time to replace it with your own app! To remove this sample app, simply remove the manifests.