When it comes to technology, you can be certain of a couple things: nobody is an expert in everything, and there are always more tools to learn. You could be a pro frontend developer who speaks multiple foreign languages and can cook a mean soufflé, but eventually you'll find yourself in the same boat as the 99% of people who aren't experts; you may discover that you're... a beginner.

One of the biggest challenges when you pick up new software is, well, where do you begin? Documentation can be suffocating. Trial-and-error is a sketchy way to try and learn how to do something correctly. Oh, and who doesn't feel guilty after they've blown up their teammates with Slack questions?

Well, this guide is for the people, the 99% of us who want some quick hands-on experience to build context around. That's not to say you'll be an expert after this, but you'll be on your way.

Let's jump in.

So, here you are, on a team that uses Ambassador Cloud for your Kubernetes workflow.

Welcome aboard.

Everyone knows it can be rough adopting new software into your workflow. Maybe you still long for the simple days of the PHP monolith when you built everything locally, before you had to deal with Kubernetes environments with a hundred microservices across your clusters. Or maybe your resume is more of a “aspirational” document. Nobody’s making judgements.

Either way, we all know the days of running all your services at once on a monolith application are rightfully over. It wasn’t the best solution. Does that mean it’s going to be a headache if you want to make a simple change, though? Nah, we’re here with a Cloud-based painkiller designed to relieve the headaches of Kubernetes development and simplify your workflow.

With Telepresence, you can create an “intercept” of service to code easier. The coding changes you make on the intercepted service can be viewed as if you were running the cluster on your laptop. It’s simple. No long waits or build time = more time to code.

This guide walks you through a quick hypothetical example to show how to create an intercept, make a basic change, and then use the automatically generated preview link to send to your teammates to impress them with how quickly you’re getting the hang of things.

The Situation

Let’s say you’re doing some front end development. You already have Git access, and Ambassador Cloud has been set up so that all the services for your clusters are displayed. Your team has been working on a new feature, and you need to add a new button style to the CSS to show them how it’ll look on the app.

All you need to do is add the button to the CSS, make sure it looks classy, and then show off what it looks like live. With an intercept, you can test your work and share a preview link so that others can see the results in a matter of minutes.

Ambassador Cloud Connection

To begin, let’s open Ambassador Cloud and take in the view.

All your services are listed.

At the top of the page you’ll see the not connected icon. Click the icon to open the dropdown and click connect to open the “Connect computer” slideout.

In the slideout, you’ll see a two or three steps listed, depending on your operating system. Follow the steps and enter the listed commands in your command prompt to download and login to it Telepresence.

You’re now connected and ready to make some changes.

Create an intercept

The moment we’ve all been waiting for: intercept time.

To begin, let’s return to that Connected icon in Ambassador Cloud. Click the Connected icon, hover over the connected cluster you’re working on, and the Intercept button will show up. Click the Intercept button to open the “Intercept Requests to a service” slideout.

The available services on the cluster are all listed here. Select the service you want to make changes on and you’ll see two questions:

• How do requests enter the cluster? Open the dropdown and select the way requests enter the cluster.
• What port handles requests to the service? - Enter the port number for local requests.

Once you’ve taken care of those questions, click the Intercept button.

The intercept is created. Nice one! Are you sure this is your first time?

The slideout now displays the preview URL and the HTTP header details. Don’t worry about the HTTP header stuff for now. The preview URL is what we’re here for.

If you go back to the Services page in Ambassador Cloud, you can see the service you intercepted listed on the page with a green intercept icon next to it. Now we can make those CSS changes and see how they look before we send it off to the team.

Make a change

Now it’s just like the good ol’ days, only easier. You can make your changes as you normally would, then send the preview off to your team so they can look at the changes as if they had the same environment build on their computers.

So, open your editor of choice and make those CSS changes on your local repo. Add a new button, maybe put a little border on the radius, adjust the padding, maybe add a focus pseudo-class to jazz it up a bit. Do what feels good, then save your changes.

Now it’s time to go to the preview URL for the intercept. Head back to the Ambassador Cloud Services page and click on the intercept . In the intercept’s service details page, click Activities and the preview URL will be shown on the page. Click on it to open the service and see your work.

Since that new button you created is looking sweet, then why not reap your due praise? Slack the preview URL to some people on your team and then they can see the changes running on your laptop as well.

See? Way easier than the days of the PHP monolith. Welcome to the new “good ol’ days.”

Annotations allow you to add metadata to objects for purely informational purposes. It's a wildly helpful practice, and let’s be honest: it's a practice that can be difficult to remember to maintain. No doubt a lot of the information you need is tucked away in internal wiki pages, online drives, or emails you've flagged.

Ambassador Labs has its own set of custom annotation keys that can be added to your services. These annotations allow you to populate the services in Ambassador Cloud with a wealth of useful information so that anyone looking at the service can see things like the owner of the service, the git repo associated with it, and links to documentation and support.

The Situation

You just started working for a company called The Pirate Ships. They’re app-based company that connects hungry sailors with local sea-faring pirates who perform maritime food deliveries for gig work in their free time.

The Pirate Ships uses Ambassador Cloud to manage its Kubernetes development, and your first job with the company is to help manage the employee database service. Naturally, you’re a responsible person and want to add some annotations to the service to keep things clearly organized.

Ambassador Cloud Connection

Second verse, same as the first: open Ambassador Cloud.

At the top of the page you’ll see the not connected icon. Click the icon to open the dropdown and click connect to open the “Connect computer” slideout.

In the slideout, you’ll see a two or three steps listed, depending on your operating system. Follow the steps and enter the listed commands in your command prompt to download and login to it Telepresence.

Create your annotations

Find a service you want to create a mapping for and click on it to go to the service details page. In the Details view, you can see the metadata information—or lack thereof—associated with the service. Click Add Metadata to open the Service Annotations slideout.

The slideout contains an example yaml file. Copy the yaml to your clipboard and paste it into your text editor. For the time being, we just want to add three annotations to the service:

• A description of the service
• Your contact information
• Your team’s slack channel

To add these, go to the annotations yaml text you pasted into your text editor and add the details as follows:

apiVersion: v1

kind: Service

metadata:

name: the-pirate-ships

namespace: the-pirate-ships

annotations:

a8r.io/description: “The Pirate Ships’ Crew Quarters.”

a8r.io/owner: “peg_leg@thepirateships.com”

a8r.io/chat: “#thepirateships-scallywag-services“

When you’re done, save the file as employee_db_service.yaml.

Next, open your command line tool and apply the changes with the following command:

kubectl apply -f employee_db_service.yaml

Go back to Ambassador Cloud and refresh the service’s page. You’re now listed as the owner, and the Slack and Service Descriptions have been updated accordingly. You're starting to look like a seasoned seadog already.

To paraphrase the current docs, “Ambassador Labs’ Edge Stack is designed around a declarative, self-service management model which is heavily dependent on the Mapping custom resource.”

Woof. Chances are, that sentence is going to raise more questions than answers. The Mapping custom resource is such a central part of how routing is handled in Edge Stack that it deserves a better explanation than that.

The Mapping resource defines how incoming traffic is handled. Additionally, the attributes in the Mapping resource provide context for other functions in Ambassador Cloud, such as canary deployments and rate limiting. Basically, the Mapping resource is like the air traffic controller for your cluster.

The Situation

After your success updating the annotations at The Pirate Ships, you’ve been asked to route all traffic from the “/new-castaways/” prefix in the “www.the-pirate-ships.com/new-castaways/” section of the app to the new “deserted-island.org” namespace.

To do this, you need to create a new Mapping resource for the service. Fortunately, Ambassador Cloud has a simple way of creating these mappings and upload them to Git.

Ambassador Cloud Connection

You know the routine by now. Open Ambassador Cloud and get connected.

Create a Mapping

Find a service you want to create a mapping for and click on it to go to the service details page. In the lower-right section of the details page, you can see any existing service mappings listed.

Click New Mapping to open the “Generate Mapping” slideout. Here, you to define any relevant data to the Mapping. Because this is a relatively basic Mapping, we’ll be focusing on the first two sections of this slideout: “Match Traffic” and “Rewrite Traffic”.

For the Mapping Name, enter “Anchors Aweigh” or “Treasure Mapping” or whatever suits your tastes. Then, for the Host Matching section in the Match Traffic section, click Yes on the slider to the right. Enter “/new-castaways/” to designate that the Mapping applies to anything with that in the path.

Next, click Yes next to Host Rewrite in the Rewrite Traffic section. In the Host Rewrite field, enter the namespace the traffic is being rewritten to, “deserted-island.org”.

Click Generate Mapping to create a yaml file with the new Mapping resource.

Now, the magic begins. Because Ambassador Cloud is connected to your Git repo, you can click where it says “Sick of YAML?” and Ambassador Cloud will create a pull request with the updated yaml Mapping.

That's it, folks. The guide's over.

Feel free to let you friends and family know: you are no longer an Ambassador Cloud beginner... now, you're an amateur. Keep going. Go on and venture into the documentation to continue your journey, or check out any of the other Kubernetes Learning Center courses on our site to keep up that expert-bound momentum!