Skip to main content

Change a Service

In this guide, we'll explore how Holos supports the frontend development team at Bank of Holos in reconfiguring an already deployed service. Along the way, we'll demonstrate how simple configuration changes are made safer with type checking, and how rendering the complete platform provides clear visibility into those changes.

This guide builds on the concepts covered in the Quickstart and Deploy a Service guides.

What you'll need​

Like our other guides, this guide is intended to be useful without needing to run each command. If you'd like to apply the manifests to a real Cluster, complete the Local Cluster Guide before this guide.

You'll need the following tools installed to run the commands in this guide.

  1. holos - to build the Platform.
  2. helm - to render Holos Components that wrap Helm charts.
  3. kubectl - to render Holos Components that render with Kustomize.

Fork the Git Repository​

If you haven't already done so, fork the Bank of Holos then clone the repository to your local machine.

# Change YourName
git clone https://github.com/YourName/bank-of-holos
cd bank-of-holos

Run the rest of the commands in this guide from the root of the repository.

If you plan to apply the changes we make, you can delete and re-create your local platform synced to the start of this guide.

./scripts/reset-cluster
./scripts/apply

Rename the Bank​

Let's imagine the bank recently re-branded from The Bank of Holos to The Holistic Bank. The software development team responsible for the front end website needs to update the branding accordingly.

Let's explore how Holos catches errors early, before they land in production, then guides the team to the best place to make a change.

The bank front end web service is managed by the projects/bank-of-holos/frontend/components/bank-frontend/ component which refers to the organization display name in schema.gen.cue.

package holos

import api "github.com/holos-run/holos/api/author/v1alpha4"

// Define the default organization name.
_Organization: api.#OrganizationStrict & {
	DisplayName: string | *"Bank of Holos"
	Name:        string | *"bank-of-holos"
	Domain:      string | *"holos.localhost"
}

// Projects represents a way to organize components into projects with owners.
// https://holos.run/docs/api/author/v1alpha4/#Projects
_Projects: api.#Projects

// ArgoConfig represents the configuration of ArgoCD Application resources for
// each component.
// https://holos.run/docs/api/author/v1alpha4/#ArgoConfig
_ArgoConfig: api.#ArgoConfig

#ComponentConfig: api.#ComponentConfig & {
	Name:      _Tags.name
	Component: _Tags.component
	Cluster:   _Tags.cluster
	ArgoConfig: _ArgoConfig & {
		if _Tags.project != "no-project" {
			AppProject: _Tags.project
		}
	}
	Resources: #Resources

	// Mix in project labels if the project is defined by the platform.
	if _Tags.project != "no-project" {
		CommonLabels: _Projects[_Tags.project].CommonLabels
	}
}

// https://holos.run/docs/api/author/v1alpha4/#Kubernetes
#Kubernetes: close({
	#ComponentConfig
	api.#Kubernetes
})

// https://holos.run/docs/api/author/v1alpha4/#Kustomize
#Kustomize: close({
	#ComponentConfig
	api.#Kustomize
})

// https://holos.run/docs/api/author/v1alpha4/#Helm
#Helm: close({
	#ComponentConfig
	api.#Helm
})

Line 7 of the schema.cue file defines the default value for _Organization.DisplayName by using string | *"...". In CUE, the * asterisk character denotes a default value.

Line 78 of the bank-frontend.cue file refers to _Organization.DisplayName to configure the front end web container.

Let's change the name of the bank by defining a new value for _Organization.DisplayName at the root of the configuration. Create projects/organization.cue with the following content.

package holos

_Organization: DisplayName: "The Holistic-Bank"

Let's render the platform and see if this changes the name.

holos render platform ./platform
Whoops

The development team defined a value that isn't allowed by the configuration.

Someone else in the organization placed a constraint on the configuration to ensure the display name contains only letters, numbers, and spaces. This constraint is expressed as a regular expression.

tip

CUE provides clear visibility where to start looking to resolve conflicts. Each file and line number listed is a place the #Organization.DisplayName field is defined.

Let's try again, this time replacing the hyphen with a space.

package holos

_Organization: DisplayName: "The Holistic Bank"
holos render platform ./platform
Success

Great, the platform rendered. We know the display name is valid according to the constraints.

Let's see if the new display name value updated the configuration for the bank frontend.

git status
git diff
danger

The new display name changed the frontend container, but it also affected the app-projects component owned by the platform team.

Submitting a pull request would trigger a code review from the platform engineering team who manages the app-projects component. Let's see how to narrow the change down to limit the scope to the bank's user facing services. All of these services are managed under projects/bank-of-holos/ Move the organization.cue file into this folder to limit the scope of configuration to the the components contained within.

mv projects/organization.cue projects/bank-of-holos/

Render the platform and let's see what changed.

holos render platform ./platform
git diff
Success

Great! This time, the only manifest affected is our bank-frontend.gen.yaml.

The BANK_NAME environment variable will change as we expect, and only the dev teams managing the bank services components are affected by the change.

Let's commit and push this change and see if it works.

git add .
git commit -m 'frontend: rename bank to The Holistic Bank'
git push

Now that we've pushed the change, let's apply the change to the platform.

Apply the Change​

Once we've pushed the change, navigate to the bank-frontend GitOps Application. We can see the Deployment needs to sync to the desired state we just pushed.

bank-frontend out of sync

Clicking on the frontend Deployment, we see the diff with the change we expect.

bank-frontend diff

Sync the change, ArgoCD applies the desired configuration state to the cluster and Kubernetes handles rolling out the updated Deployment resource.

bank-frontend progressing

Soon, the deployment finishes and the component is in sync again.

bank-frontend in sync

Finally, let's see if the name actually changed on the website. Navigate to https://bank.holos.localhost/.

bank-frontend login page

Success

We successfully made our change and successfully applied the changed configuration to the platform.

Thanks for taking the time to work through this guide which covered:

  • How multiple teams could be impacted by defining configuration at the projects/ path.
  • How to scope our change to only affect components within the projects/bank-of-holos/ path, eliminating the impact on other teams.
  • How CUE can constrain values in Holos, increasing safety.
  • How to handle a default value in CUE.
  • How CUE surfaces the file and line number of every place to look for where a value is defined, making it faster and easier to troubleshoot problems.