Skip to main content

Ingress to Kubernetes apps deployed on Spectro Cloud Palette

TL;DR

To use the ngrok Kubernetes Ingress Controller with Spectro Cloud Palette:

  1. Create an add-on cluster profile for the ngrok Kubernetes Ingress Controller
  2. Create your cluster with Palette
  3. Create an add-on cluster profile for an example app and ngrok Kubernetes Ingress Controller
  4. Create your cluster with Palette

The ngrok Ingress Controller for Kubernetes is the official controller for adding public and secure ingress traffic to your k8s services. This open source Ingress Controller works with any cloud, locally-hosted, or on-premises Kubernetes cluster to provide ingress to your applications, APIs, or other services while also offloading network ingress and middleware execution to ngrok's platform.

Palette, from Spectro Cloud, is a profile-based Kubernetes management platform. It gives IT teams the control and visibility to create Kubernetes stacks for their developers with all the granular governance and security they need.

Together, the ngrok Ingress Controller and Palette integrate to provide secure public ingress for apps running on Kubernetes clusters managed on their platform. You get all the benefits of declarative management and lifecycle controls in Palette while simplifying and securing how you move public traffic into your Kubernetes cluster.

With this guide, you'll define cluster and add-on profiles in Palette, create a cluster with your cloud provider, and integrate the ngrok Kubernetes Ingress controller with either an example app or a custom app you're ready to make public via ngrok's Cloud Edge.

This tutorial requires:
  1. An ngrok account at any tier.
  2. A Palette account with Spectro Cloud.
  3. An account with the necessary privileges to create a cluster on one of the following managed Kubernetes services:

Step 1: Create a cluster profile in Palette​

Palette uses infrastructure-level cluster profiles to help you create and deploy a Kubernetes cluster with your service of choice. Profiles are layers of Helm charts, manifests, and packs provided by Palette to repeatedly deploy clusters to multiple providers and manage them in Palette.

If you already have a cluster profile, skip to Step 4: Create your cluster with Palette. If you already have a functioning cluster in Palette, skip to Step 3: Create an add-on cluster profile for an example app and ngrok Kubernetes Ingress Controller.

  1. Log in to your Palette account.

  2. Click Profiles in the navigation, then Add Cluster Profile. In the Basic Information tab, give your profile a name, like ngrokker, and a version. For this guide, leave the Type as the default Full, then click Next.

    Add a cluster profile name and version

  3. In the Cloud Type tab, choose your provider.

    Choose a Kubernetes provider for your profile

  4. In the Profile Layers tab, click on your base OS pack—in most cases, there will be a single option, like Container-Optimized OS or Linux. This is where you would add customizations or additional manifests, but you can leave the settings at their default and click Next layer.

    Select packs and options

    Repeat the process for the base Kubernetes, Network, and Storage packs. At the final step, click Confirm.

  5. Palette now shows you the layers of this new cluster profile. You can also add new Packs, manifests, or Helm charts, but to save your progress for now, click Next, then Finish Configuration.

    Finalize your cluster profile

Step 2: Create an add-on cluster profile for the ngrok Kubernetes Ingress Controller​

You've defined the core layers of your cluster and created it, but you don't currently have a method of handling traffic ingress.

For the former, Palette has a ready-to-apply pack for the ngrok Kubernetes Ingress Controller. For the latter, you can either add an example app as detailed in the following steps or connect to an existing app.

  1. Head back to the Profiles section in Palette. Click on Add Cluster Profile. Give this profile a name. Under Type, click the Add-on option, then Next.

  2. Click Add New Pack, then either search ngrok, or scroll down to the Ingress section, and click on the ngrok Kubernetes Ingress Controller icon.

    Add the ngrok Ingress Controller pack

  3. Scroll down in the default YAML supplied by the pack to the following configuration.

    ## @param credentials.secret.name The name of the secret the credentials are in. If not provided, one will be generated using the helm release name.
    ## @param credentials.apiKey Your ngrok API key. If provided, it will be will be written to the secret and the authtoken must be provided as well.
    ## @param credentials.authtoken Your ngrok authtoken. If provided, it will be will be written to the secret and the apiKey must be provided as well.
    credentials:
      secret:
        name: ""
      apiKey: ""
      authtoken: ""

    You must specify the apiKey and authtoken parameters with those of your ngrok account.

    To create a new API key, navigate to the API section of the ngrok dashboard, click the New API Key button, change the description or owner, and click the Add API Key button. Copy your new API key into the apiKey parameter.

    Find your AUTHTOKEN under Your Authtoken in the ngrok dashboard, and copy that into the authtoken parameter.

    Palette will automatically hide the values you enter.

    Add ngrok secrets to the Palette profile

    tip

    If you have a free ngrok account, you can only have one ngrok agent active at a time. To ensure the ngrok Kubernetes Ingress Controller functions properly in production, set the replicaCount parameter to 1.

  4. Click Confirm & Create to add the layer to your profile and then finish the configuration.

Step 3: Create an add-on cluster profile for an example app​

  1. Create an ngrok static subdomain for ingress, if you don't have one already. Navigate to the Domains section of the ngrok dashboard and click Create Domain or New Domain. This static subdomain will be your NGROK_DOMAIN for the remainder of this guide.

  2. Create a new cluster profile, name it game-2048, and click the Add-on profile type.

  3. Click Add Manifest to create a new layer using Kubernetes manifests in YAML.

    Name the layer 2048, then click New manifest and name it deployment. Copy the following YAML content to create a Kubernetes deployment named game-2048.

    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: game-2048
      namespace: ngrok-ingress-controller
    spec:
      replicas: 1
      selector:
        matchLabels:
          app: game-2048
      template:
        metadata:
          labels:
            app: game-2048
        spec:
          containers:
            - name: backend
              image: alexwhen/docker-2048
              ports:
                - name: http
                  containerPort: 80

    Create a second manifest named service copy in the following YAML:

    apiVersion: v1
    kind: Service
    metadata:
      name: game-2048
      namespace: ngrok-ingress-controller
    spec:
      ports:
        - name: http
          port: 80
          targetPort: 80
      selector:
        app: game-2048

    Click Confirm & Create to save the deployment.

  4. Add another manifest to create a Kubernetes ingress service, which will inform the ngrok Kubernetes Ingress Controller to create a new Edge for your app. Name it 2048-ingress and create an ingress manifest with the following YAML content, replacing the NGROK_DOMAIN variable with the subdomain you created, which should look like one-two-three.ngrok.app.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: game-2048-ingress
      namespace: ngrok-ingress-controller
    spec:
      ingressClassName: ngrok
      rules:
        - host: NGROK_DOMAIN
          http:
            paths:
              - path: /
                pathType: Prefix
                backend:
                  service:
                    name: game-2048
                    port:
                      number: 80

    Click Confirm & Create once again to add this layer before finishing the configuration.

    Finish creating 2048 profile

Step 4: Create your cluster with Palette​

You can now create your core cluster using Palette and your cloud provider. Once the cluster deploys, you'll add additional layers for an example app and the ngrok Kubernetes Ingress Controller.

  1. Navigate to Project Settings in the Palette dashboard to add a cloud account.

    Before connecting your cloud account to Palette, ensure you have user/service account privileges. Doing so is beyond the scope of this guide, but the Palette docs have detailed requirements for GCP, AWS, Azure, and others.

    For example, GCP requires a service account with the following credentials:

  2. Click Add ... Account to open a modal containing the credentials required to connect your account. For GCP, you only need to upload the JSON credentials for your service account.

  3. Click Validate. If there are any errors, Palette will attempt to explain what privileges are missing, or settings not yet enabled in your cloud account, and provide links to relevant docs.

  4. Start the cluster setup process by clicking Clusters in the left-hand navigation, then Add New Cluster, and Deploy New Cluster.

  5. Choose your cloud provider and start the configuration. Give your cluster a name, then choose the cloud account you connected to Palette.

  6. Find the cluster profile you created in Step 1 and click Next.

    Choose your cluster profile

  7. Add your additional profiles by clicking on the + next to Addon layers. Choose the ngrok Kubernetes Ingress Controller profile, then repeat for the 2048 game profile.

    You have one more opportunity to customize the configurations, but you can click Next to continue.

  8. Choose the Project you'd like to create your new cluster within and pick a region.

    tip

    A common error at this stage is you still need to activate certain APIs for your project. For example, a project in GCP requires the Compute Engine API, which in turn requires an enabled billing account. Once you fix these errors, give the settings a few minutes to propagate to Palette, before moving forward.

  9. Next, create your node pool. Here, you can change the number of nodes in the pool and specify the instance type you'd like to use.

    Selecting the cluster's node pool

  10. Click Finish Configuration to create your cluster.

    The final visualization of the cluster with all profiles

    The deployment process may take up to 15 minutes, depending on your cluster profile, node pool configuration, and the general load on that region. You can track the provisioning process on the cluster's Overview.

    If you see additional errors during deployment, view the Events tab to read logs and check whether you need to enable additional APIs or privileges on your project or service account.

  11. Once Palette reports your cluster as Running, you can open your browser and navigate to your NGROK_DOMAIN to see your example app as managed, deployed, and publicly networked via, respectively, Palette, Kubernetes, and ngrok!

    Viewing the final 2048 game

What's next?​

You have now used Spectro Cloud's Palette to create modular, declarative configurations for your cluster, then deployed an example Wordpress app integrated with the ngrok Kubernetes Ingress Controllers. With ngrok operating as your middleware, handling ingress to your Palette-managed Kubernetes cluster, you can deploy any number of apps while maintaining control and customization.

From here, you have a few options:

Clean up​

Delete your Palette-managed cluster by heading to the Overview for your cluster, then clicking Settings → Delete Cluster. Palette will send the necessary requests to your provider to delete your cluster resources.

ngrok will automatically delete your Edge upon the deletion of your cluster.

Extend your ngrok Kubernetes Ingress Controller and Palette integration​

You can use the ngrok Kubernetes Ingress Controller and Palette to manage multiple routes on a single Edge using name-based virtual hosting or route modules. Custom domains and a circuit breaker are also good next steps to make your integration production-ready.

Learn more about the ngrok Ingress Controller, or contribute, by checking out the GitHub repository and the project-specific documentation.