Skip to main content

Codiac Quickstart Guide 2: Walkthrough

This quickstart guide walks you through the process of setting up your Codiac account, deploying an asset, and configuring DNS.

Prerequisites​

Part 1 and 2
Part 3

Part 1: Account Setup​

In this part, you create:

  • An enterprise named main.
  • A cluster named test-cluster on your cloud service provider.
  • An environment named test-environment.
  • A cabinet named test-cabinet.

1. Create an enterprise​

You created a tenant when you set up your Codiac account. The next scope to create is the enterprise. An enterprise is a grouping of clusters, assets, and environments.

  1. Use codiac enterprise create to create an enterprise:
codiac enterprise create

Name your enterprise main.

2. Create a cluster​

The next step is to create a cluster on your cloud service provider.

tip

When the cluster creation is complete, you can log into your cloud service provider to view the cluster details.

  1. Use codiac cluster create to create a new cluster on your cloud service provider:
codiac cluster create
  1. Follow the prompts to:

i. Select your cloud service provider.

ii. Name your cluster test-cluster.

iii. Select the parameters you want to set for your cluster, including the region, node type, etc. For the purpose of this guide, select all the default options for these parameters.

Verify all the parameters are correct, then enter Y to start the cluster creation process.

3. Create an environment​

An environment is a grouping for cabinets within the enterprise. Environments can span multiple clusters and are a convenient way to group workloads by team, like dev, prod, and demos.

  1. Click + on the main page to create a new environment.

Create a new environment

  1. Name your environment test-environment.

  2. Select the test-cluster cluster you created in step 3.

  3. Click Confirm to create the new environment.

Confirm creation of a new environment

4. Create a cabinet​

A cabinet is a space for you to run your collection of assets together as an isolated instance of your enterprise. Cabinets are grouped by environment and are provisioned on a single cluster.

tip

Cabinets are a convenient way to separate projects within an environment being shared by a team. For example, you could create separate sandbox, qa, and staging cabinets in the same environment.

  1. Click + in your new environment to create a cabinet.

Create a new cabinet

  1. Name the cabinet test-cabinet.

  2. Click Confirm to create the new cabinet.

Confirm creation of a new cabinet

You now have a cabinet created with a cluster assigned.

Part 2: Create and Deploy an Asset​

This part of the guide walks you through creating and deploying an asset to your Codiac cabinet:

  • Use an image from Docker Hub to create an asset with ingress.
  • Deploy the asset into your test-cabinet.
  • Verify the deployment.
tip

Ingress lets you access the asset from the public internet. Codiac's streamlined ingress creation process means all you have to do is answer a few questions during the codiac asset create process. Codiac handles the rest.

5. Create an asset​

An asset is a workload you create from an image stored on a container registry like Docker Hub or Azure Container Registry.

tip

This tutorial specifies the official Docker NGINX image. If you have your own Docker image, feel free to use that instead.

  1. Use codiac asset create to create a new asset:
codiac asset create

Follow the prompts to create your test asset:

  1. Select your Codiac tenant.

  2. Select the main enterprise you created in Quickstart 1.

  3. Select a container registry. For this Quickstart, choose the official DockerHub registry:

Choose Docker Hub

  1. Log into Docker Hub with your Docker Hub credentials.

  2. Scroll down and select the NGINX image.

  3. Name this asset test-nginx.

  4. Choose the default port number. For this tutorial, choose port 80.

The default port number is where Codiac will configure ingress. Port 80 is standard for web applications like NGINX.

  1. For Port 1: Forwarding? answer N.

  2. For Assign another port? answer N.

  3. For Accessible from outside the cabinet (aka: has ingress route), answer Y.

Answering Y tells Codiac to configure ingress, which lets you access the cluster from the public internet. In the future, if you don't want the cluster to have ingress, answer N to this question.

  1. For Usage: external answer Y.

  2. For Host name on the inbound domain url, answer quickstart.

This host name will come into play in the next Quickstart, when you configure DNS. The name you set here will be used as the service name for the URL.

  1. For Will this asset be the base ingress against your DNS, answer N.

This step is part of Codiac's strategy-based host mapping, which we will cover in the next Quickstart guide. For now, know that you can only have one base ingress URL for your account. You probably don't want it to be this test asset. Save base ingress for your main application and answer N for now.

  1. For Continue? (y/N), answer Y.

6. Deploy the asset​

Now that you have created your asset and configured ingress, it's time to deploy it into your cabinet.

tip

The first time you deploy an asset, it must be from the command line. After that, you can deploy an asset from the web by clicking and dragging it from the Asset Inventory slide-out panel into your cabinet.

  1. Use codiac asset deploy to deploy the asset:
codiac asset deploy
  1. Follow the prompts to:

i. Select your asset from the list.

ii. Log into Docker Hub with your Docker Hub credentials.

iii. Select the Docker Hub asset version.

iv. Select your test-cabinet for the deployment.

v. If necessary: Follow the prompts to log into your cloud service provider account.

7. Verify the deployment​

Use one or more of the following methods to verify your asset deployment.

Option 1: List assets (CLI)​

Use codiac asset list to list all deployed assets on your account:

codiac asset list

The asset is listed here, along with any other deployed assets.

Option 2: View asset details (CLI)​

  1. Use codiac asset view to view details about the asset:
codiac asset view

  1. Select your test-nginx asset and test-cabinet cabinet.

  2. Select which details you want to view.

For example, you can view the asset's status:

$ codiac asset view
? Asset:  test-nginx
? Cabinet: test-cabinet  Yes
? Type of content:  status
Continuing in azure as [jdoe@example.com (Subx:1230abc-90a9-4b12-a123-123456789)]
Authenticating with azure...... Success!
Watching test-nginx in test-environment/test-cabinet... (ctrl-c to quit)
1.27.1
  57f64d577d-r4jmr) Running PodReadyToStartContainers since (Fri Sep 27 2024 15:04:12 GMT-0700 (Pacific Da
ylight Time)) started (Fri Sep 27 2024 15:04:05 GMT-0700 (Pacific Daylight Time)) 0 restarts
  57f64d577d-wp2jz) Running PodReadyToStartContainers since (Fri Sep 27 2024 15:04:11 GMT-0700 (Pacific Da
ylight Time)) started (Fri Sep 27 2024 15:04:05 GMT-0700 (Pacific Daylight Time)) 0 restarts

Option 3: View asset details (Web)​

From the web, select your cabinet to view the asset details:

Show deployed asset

Part 3: Configure DNS​

This part of the quickstart guide walks you through configuring DNS so you can access your Codiac asset from the internet.

8. Host map​

  1. Use codiac host map to assign DNS routing to your asset:
codiac host map
  1. For Domain: enter your domain name. For example, example.com.

This specifies the domain name Codiac will use for your URL.

  1. For Scope: select cabinet, then select the main/test-environment/test-cabinet you created in the previous Quickstart guides.

This specifies the scope of your domain name. You can scope a domain name to your enterprise, environment, or cabinet.

tip

Codiac Scopes: (tenant [enterprise {environment (cabinet)}])

  • A tenant contains enterprise(s).
  • An enterprise contains environment(s).
  • An environment contains cabinet(s).
  • A cabinet contains asset(s).

For this exercise, we will select the least scope (cabinet).

  1. For Host naming strategy, select svc.cab.domain.

This step specifies the configuration for Codiac's strategy-based host mapping. Codiac has many strategies available, depending on how you want to access your asset.

This particular host naming strategy is:

  • svc: The service name you set in response to "Host name on the inbound domain url" when you ran codiac asset create in Quickstart 2: quickstart.
  • cab: Cabinet.
  • domain: Domain name.

For:

  • service name: quickstart
  • cabinet test-cabinet
  • domain example.com

The URL to access your asset is: https://quickstart.test-cabinet.example.com.

  1. For Continue? (y/N), answer Y.

9. Update DNS​

  1. Use codiac host view to get your assigned IP address:
codiac host view
  1. The output of this command ends with the DNS information you need to update your name servers:
dnsRequired:
  example.com:
    - recordType: A
      host: "*"
      destinationIp: 172.202.238.6
    - recordType: A
      host: "@"
      destinationIp: 172.202.238.6

  1. Using this information, update the DNS for your domain name to add or edit:
  • An A record with host name * and the destinationIp address.
  • An A record with host name @ and the destinationIp address.
tip

The process for updating your DNS varies depending on your domain registrar or name server hosting provider. If you need help with this step, contact their support.

10. Verify DNS​

  1. Open a browser window and go to the URL you chose as your host naming strategy in Step 1.

We chose svc.cab.domain as the host naming strategy and set the following:

  • quickstart as the service name.
  • test-cabinet as the cabinet name.
  • example.com as the domain name.

Therefore, the URL to access this asset is https://quickstart.test-cabinet.example.com.

info

The URL to access your asset always starts with https://. We use TLS configured using the industry-standard HTTP-01 challenge methodology. This lets us create a self-signed SSL certificate for all Codiac ingress routes.

  1. The default NGINX landing page appears:

Default NGINX landing page