How To Start Nginx Service In Kubernetes Using Ansible

Recently, we appear the release of the Ansible collection for NGINX Controller. The collection contains a set of Ansible Roles that brand it easy to incorporate NGINX Controller into your workflows. You can automate routine tasks such as generating ephemeral API tokens, managing certificate lifecycles, and configuring Controller objects (Gateways, Applications, and Components).

If you're an Ansible Automation Platform subscriber, yous tin can access the certified collection on Ansible Automation Hub. The upstream, community version is on Ansible Milky way. The NGINX Controller Ansible Tower examples are in my GitHub repository.

NGINX Controller is our cloud‑agnostic control‑aeroplane solution for managing your NGINX Plus instances in multiple environments and leveraging critical insights into performance and error states. Its modules provide centralized configuration management for application delivery (load balancing) and API management. Yous can go familiar with the capabilities of NGINX Controller through our instructor‑led course.

What Can You Exercise with the Drove?

Some of the roles in the collection support day-to-twenty-four hours activities such every bit:

Creating NGINX Plus instances (nginx)
Registering NGINX Plus instances with NGINX Controller, past installing the NGINX Controller agent on the NGINX Plus host (nginx_controller_agent)
Deploying and configuring NGINX Plus instances every bit gateways for routing and protecting incoming traffic (nginx_controller_gateway)
Managing application workspaces (nginx_controller_application)
Configuring components to intelligently and securely distribute traffic to your backend workloads (nginx_controller_component)
Managing certificates that are distributed by NGINX Controller to the NGINX Plus instances where they are needed (nginx_controller_certificate)
Retrieving an ephemeral API token for the NGINX Controller API (nginx_controller_generate_token)

Roles for that actions you might perform less frequently include:

Installing NGINX Controller itself; yous might want to automate installation in your lab environment every bit part of a proof of concept or trial (nginx_controller_install)
Managing your evaluation and production licenses (nginx_controller_licence)

Nosotros plan to support additional workflows in future, including user onboarding.

Overview of the Sample Scenario

This post accompanies a video in which we use sample playbooks I have written, which invoke the NGINX Controller roles, to set up an application in an AWS product environment for a fictitious customer, Height Financial, by promoting the configuration of an existing development environment. Nosotros take advantage of all the roles in the collection, likewise as the sample playbooks and Ansible Tower workflows, to:

Create new NGINX Plus instances in AWS
Register the instances to be managed by NGINX Controller
Manage certificates and configuration with NGINX Controller

Notes:

This weblog assumes familiarity with Ansible and NGINX Controller.
In the demo we use Ansible Tower to command the process flow, but you lot can employ the Ansible CLI so long as you laissez passer in extra variables on the control line.
Every bit with any organization, there are multiple implementation patterns that tin be leveraged depending on your needs. These are examples to help get you started.
To help y'all track along with the demo, we include the time points from the video in the headers.

Establishing a Credential for NGINX Controller (3:30)

Nosotros kickoff establish a new credential type for NGINX Controller in Ansible Tower. I take previously loaded the contents of the input_credential.yaml and injector_credential.yaml files from the credential_type.nginx_controller directory in my GitHub repo into Ansible Tower. The contents of these files are subject to enhancement over time, but in this demo the three important pieces are an FQDN, a user ID (email address), and a user password.

With the credential type established, nosotros establish an bodily credential called AWS NGINX Controller in Ansible Tower. I've previously entered my email address, password, and the FQDN of my NGINX Controller instance. As we go through the subsequent playbooks, Ansible Tower automatically passes the credentials as needed.

Provisioning NGINX Plus Instances in the Cloud (4:30)

Before we can promote the app from the development to production, nosotros accept to create and configure new NGINX Plus instances to host information technology. I accept created some workflow and job templates in Ansible Tower, and to begin nosotros launch the add_aws_controller_gateways workflow. It strings together playbooks from the controller_gateway_instances directory of my GitHub repo to do several things:

Create new Amazon EC2 instances
Add the instances to my Ansible Belfry inventory
Install NGINX Plus
Install the NGINX Controller agent aslope NGINX Plus

Creating Amazon EC2 Instances (five:10)

When we kick off the add_aws_controller_gateways workflow, Ansible Belfry brings up the contents of the aws_add_instance_vars.yaml file. We gear up count to 2 to create 2 EC2 instances and set environmentName to production-us-east . We go out the locationName unspecified in NGINX Controller, and verify that securityGroup, imageID, keyName, and loadbalancerPublicSubnet are set to the values nosotros desire.

While the workflow starts to run, we await in Visual Studio Lawmaking at the contents of the controller_gateway_instances directory, as shown in this screenshot. In the demo we review the contents of various files at the appropriate phase.

The two files we examine at this stage are:

collections/requirements.yml fetches the nginx_controller collection into Ansible Tower from the nginxinc namespace in Ansible Galaxy or Ansible Automation Hub, and so I don't take to mess with manually installing the roles.
add_aws_new_instance.yaml provisions the load‑balancing automobile instances in Amazon EC2. It tags them with surroundings and location names, which establishes a sortable link between the AWS infrastructure and NGINX Controller. In particular, I apply the new_gateway key as a tag to use in controlling later stages of the workflow.

Establishing a Automobile Inventory (7:08)

Ansible offers a few options to manage inventory, and the one you lot choose is really a personal preference. I took advantage of the Ansible Belfry cloud‑based inventory "source" feature instead of statically setting auto names in the inventory. In the aws_us-east-2_gateway_new inventory, we look at the details on the SOURCES tab:

In the SOURCE field, I have specified Amazon EC2.
In the Case FILTERS field, I have set a filter on the new_gateway key that was ready past the add_aws_new_instance.yaml playbook in Creating Amazon EC2 Instances.
In the SOURCE VARIABLES field, I have modified the default beliefs of setting a public IP accost as the endpoint of a host in the inventory. In this scenario Ansible Tower is running in AWS and can attain the private IP addresses of my instances, so my preference is to use them instead of publicly exposed interfaces.

At this point in the demo, Ansible Tower notifies us that the ii EC2 instances are created, and nosotros switch to the HOSTS tab to display them.

Installing NGINX Plus (8:30)

We then access the notification and approve the continuation of the workflow, to install NGINX Plus on the ii new EC2 instances that are tagged with the new_gateway central.

While the workflow progresses, nosotros review the deportment in the install_nginx_plus.yaml playbook which installs and configures NGINX Plus. The playbook uses the hosts statement to switch between performing deportment on localhost (the Ansible Tower host) and the new EC2 instances marked with tag_new_gateway.

Kickoff, on the Ansible Belfry host the playbook reads in the NGINX Plus central and certificate from Ansible Vault and decrypts them for use by the nginx office as it installs NGINX Plus on the EC2 instances.

On the EC2 instances, the playbook:

Loads the nginx_plus_vars.yaml file (which we examine in detail just below).
Invokes the official nginx role to install NGINX Plus. The office is not specific to NGINX Controller, but is included in the collection for convenience considering (equally in the demo) y'all ofttimes create new NGINX Plus instances before registering them for management by Controller.
Sets some logging parameters appropriate for the very small EC2 instance size used in the demo.

Back on the Ansible Tower host, the playbook removes the decrypted NGINX Plus primal and document to make sure they're not inadvertently exposed.

Now we examine the nginx_plus_vars.yaml file which configures NGINX Plus on our instances by:

Enabling and starting NGINX Plus
Protecting the NGINX Plus key and certificate from exposure
Enabling the NGINX Plus API, which Controller uses to manage NGINX Plus on the instances
Loading the NGINX JavaScript (njs) module

We finish this stage with a quick wait at the nginx-repo.yaml file, which has the encrypted NGINX Plus key and certificate as stored in Ansible Vault.

Registering NGINX Plus Instances with NGINX Controller (11:10)

As the workflow continues in the background, nosotros examine the install_nginx_controller_agent.yaml playbook, which registers the NGINX Plus instances with NGINX Controller by installing the Controller agent on them. The agent is the conduit for advice between an NGINX Plus instance and NGINX Controller.

As in Installing NGINX Plus, the playbook uses the hosts statement to switch between performing actions on localhost (the Ansible Tower host) and the new EC2 instances marked with tag_new_gateway.

On the Ansible Tower host, the playbook invokes the nginx_controller_generate_token part and creates an ephemeral API token that the agent will employ to communicate with NGINX Controller. This role is invoked in several of the playbooks, whenever we demand an ephemeral token for API advice with Controller.

On the NGINX Plus instances, the playbook invokes the nginx_controller_agent function to install the Controller agent.

Verifying the NGINX Plus Installation and Registration (12:05)

At this point in the demo, we receive a notification that installation of NGINX Plus and the Controller agent is consummate, so nosotros switch to Controller and look at the Infrastructure > Instances tab. We encounter the ii new instances, identified every bit 112 and 114.

From the Services > Environments tab, nosotros navigate to our new product-us-due east Surround and run into that it is not yet configured. A Controller Environment is a set of infrastructure objects managed by a designated prepare of consumers in your organization, like a specific Development or Operations team.

Looking at the Amazon EC2 dashboard, we meet that one of the instances has the new_gateway tag on information technology and another doesn't. We don't actually need to distinguish between new and one-time instances anymore, however, and when we return to Ansible Tower and corroborate the continuation of the workflow, the tag gets removed from whatsoever EC2 instances that accept information technology.

Configuring the Production Surround (14:03)

There are several configuration objects associated with a Controller Surroundings. For this demo, they are stored in GitHub: a certificate, a Gateway configuration (defining the ingress details), an Application configuration, and Component configurations. Next we pull those objects into Ansible Tower and apply them to our production-us-e Surround in Controller.

For certificates, for instance, I have set things upward and then that when I update a certificate in GitHub, Ansible Tower automatically receives a webhook notification from GitHub and updates the certificate in Controller.

Having the configuration objects in GitHub is very convenient, because we tin packet them all upwardly at any point in time and restore the Environment to that state if we need to. This is the common do good of using an external source of truth that we are already familiar with.

To configure our product environment, we launch some other workflow with the 1-promote_dev_to_X–trading template in Ansible Tower. On the DETAILS tab, we define the environmentName as production-us-east , the ii instanceNames as 112 and 114, and the ingressUris as {http,https}://trading.acmefinancial.net.

Uploading the App Document (16:33)

While the workflow progresses in the background, nosotros examine the nginx_controller_certificate.yaml playbook from the certificates_trading.acmefinancial.internet directory in GitHub (the directory was called certificate_merch.acmefinancial.net when the demo was recorded).

The playbook runs on the Ansible Tower host. It invokes the nginx_controller_generate_token role to generate an ephemeral token for the Controller API, loads the certificate and fundamental for the trading.acmefinancial.net application from the vars.yaml file, and invokes the nginx_controller_certificate function to update the certificate for trading.acmefinancial.net in Controller.

Examining the vars.yaml file, we encounter in the displayName field the proper name of the certificate as displayed in Controller, in the type field that the certificate blazon is PEM, and in the last 3 fields the names of the key, document, and document concatenation (note that the values in the demo are slightly dissimilar from the values in the GitHub file).

I key to success here is the formatting of the certificate variables. Hither I accept the key and certificate bodies existence dynamically read from files in the local directory in GitHub, but they could also be secured past Ansible Vault simply too. Withal, it is the pipe symbol (| ) in the variable definition that keeps all the line endings intact and thus results in a valid certificate or key in the variable trunk. The variable caCerts is an array of certificates for an intermediate certificate dominance, such equally if you lot were using your internal PKI.

Configuring a Gateway to Define Ingress Traffic (17:xl)

At present, we are at the bespeak of defining a Gateway. A Gateway describes how our customers achieve our application and it can service one or many ingress paths, URIs, or domains, depending on how your organisation defines how the customer reaches your network.

We examine the nginx_controller_gateway.yaml playbook from the gateway_retail.dev_trading directory in GitHub (in the demo, the directory proper name is gateway_lending.prod_public, but the contents of the file are the same). Running on the Ansible Tower host, the playbook loads the vars.yaml file and invokes the nginx_controller_generate_token and nginx_controller_gateway roles.

The key here is that an NGINX Plus instance is tied to a Gateway configuration. In fact, a single example or set of instances tin service multiple Gateway configurations. NGINX Controller generates and applies the configuration for you, all the while ensuring that instances that are sharing configurations don't have configurations applied that conflict with each other.

Configuring the Awarding and Component Paths to Back‑End Workloads (18:15)

The playbooks in the application_trading_configurations directory set up the Application and Component configurations in NGINX Controller. A Component defines a sub‑part of an Awarding, enabling you to deploy cocky‑contained pieces responsible for a detail office of the overall application. It defines which backend servers reply to requests for specific URIs under the FQDN handled by a given gateway. In our demo, each Component is built and managed past a different team.

app_trading.yaml defines the configuration of the Application itself
component_files.yaml defines the handling of requests to the /file URI
component_main.yaml defines the treatment of requests to the / URI
component_referrals.yaml defines the handling of requests to the /app3 URI
component_transfers.yaml defines the handling of requests to the /api URI

The task_app.yaml playbook configures the Application past reading in the configuration from app_trading.yaml and invoking the nginx_controller_application role.

Similarly, the task_components.yaml playbook configures Components by reading in the configuration from the component_*.yaml files and invoking the nginx_controller_component role.

Summary (20:20)

We conclude by navigating to the product-us-east Environment in Controller, under Services > Environments. Nosotros run across that our Application (Trading.Elevation.Financial.net), Certificate, Gateway are all divers. When we drill down into the Awarding, nosotros see the four Components (Transfers, Referrals, File, and Main) we configured in the previous section.

With this demo, we've shown how to promote an application from a development to a product surroundings using NGINX Controller incorporated into a pipeline controlled past Ansible roles and playbooks.

We run into the NGINX Controller drove every bit a starting identify that will abound over time through efforts from NGINX and the customs. I invite you lot to contribute to the collection and let the states know what new functionality is of import to yous.

If y'all desire to take NGINX Controller for a spin, asking a free trial or contact us to discuss your utilize cases.