This page explains how to set up Trustico® Certificate as a Service (CaaS) for Google Cloud, the small job that runs once a day inside your own Google Cloud project to issue your SSL Certificate through the Automatic Certificate Management Environment (ACME) protocol, install it in Certificate Manager, the classic Compute store or both, and reissue it before it expires, so it never needs maintaining by hand. It is written for a first-time customer who has a Google Cloud project but has never created a Cloud Run job.
Each part of the setup is described here by what it is and why it is there. The exact screens and values are kept in two documents, the Google Cloud ACME setup guide and the job configuration file, and each one is linked below at the end of the paragraph that describes it.
The setup guide takes you from nothing to a running job, one screen in the Google Cloud console or one command in Cloud Shell at a time. It is written so that an Artificial Intelligence (AI) assistant can follow it with you. Give your assistant the address of the guide and ask it to walk you through the steps one at a time. Download The Google Cloud ACME Setup Guide File 🔗
The job configuration file is one text file that holds every setting of the job, and it is the only configuration there is. You put your own values in place of its placeholders in any text editor and hand it to Google to create the job. Keep it, because every later change to the job is an edit to this file. Download The Cloud Run Job Configuration File 🔗
Public Container Image
The job runs from a public container image that Trustico® publishes. Any Google Cloud project can download it without a Trustico® account, and the job configuration file already names it.
us-east1-docker.pkg.dev/trustico-x/caas-gcp-01/caas-gcp-01:latest
The image is published under one name only, latest. Trustico® publishes each approved update under that same name and your job takes it on its next run, so there is nothing to apply and nothing to edit. The first line of every run names the version and the build that ran.
Supported DNS Providers
To prove that you control the names on your SSL Certificate, the job writes a small temporary record in the Domain Name System (DNS) of your domain, through the Application Programming Interface (API) of your provider. This is done by lego, the Automatic Certificate Management Environment (ACME) client inside the image, and this job runs lego v5.5.2.
Your provider must be one that lego supports. The documentation for lego lists every provider with the variables each one needs, but it describes the latest release, so a provider is available only if the page shows it as present at v5.5.2 or earlier. One provider is used per job, and if Google Cloud hosts your Domain Name System (DNS) in the same project as the job, no credential is needed. Learn About Domain Name System (DNS) Providers in lego 🔗
Setup Steps
Setup is a one-time sequence of seven steps that takes about thirty minutes. You need your Trustico® Certificate as a Service (CaaS) subscription with the three values that came with it, access to the Domain Name System (DNS) of your domain, and an account on the project with the Owner role, because the Editor role cannot grant the permissions the steps ask for.
Each step below says what it is and why it is needed, and the setup guide gives every screen and every value for it. Download The Google Cloud ACME Setup Guide File 🔗
Step 1 : Enable the APIs
Each Google Cloud service the job uses must first have its Application Programming Interface (API) enabled in your project. That means Cloud Run to run the job, Cloud Scheduler to start it each day, and Certificate Manager to hold your SSL Certificate, with the Compute Engine API as well if you use the classic Compute store. Secret Manager and the Google Cloud service for the Domain Name System (DNS) are enabled only when you use them.
Step 2 : Create the Bucket
A Cloud Run job has no disk of its own, because every run starts empty and keeps nothing when it ends. The job therefore keeps its account, every SSL Certificate and the Private Key of each one in a private Cloud Storage bucket in your project. Object versioning is switched on so that the Private Key and SSL Certificate a reissue replaces are kept as your way back. The guide gives the number of older versions to keep and how long to keep them, because the defaults the form offers would delete them a day after a reissue.
Step 3 : Create the Service Account
A service account is the identity a program runs as in Google Cloud. With one of its own, the job holds only the permissions it needs and has no access to anything else in your project. It receives a role for each store you chose, a role in the project that holds your zone if Google Cloud hosts your Domain Name System (DNS), and access to the one bucket from Step 2. Google shows an e-mail address for it, which you write down for the job configuration file.
Step 4 : Prepare the Job Configuration File
The job configuration file holds every setting of the job, so you fill it in once by hand and give it to Google in one go, instead of entering each field in the console. Replace each placeholder with your own value, guided by the comment directly above it. The secret key of your subscription and the credential of your provider can be kept in Secret Manager instead of in the file, and the guide shows how.
Step 5 : Create the Job
This step turns your job configuration file into a Cloud Run job. The surest way is to upload the file to Cloud Shell, the terminal built into the console, and run the one command the guide gives, with the region you choose. The console form works too, with every value from the job configuration file entered field by field, and the guide names the two task settings whose defaults must be changed. Uploading the edited file to Cloud Shell again and running that command again is what the guide calls applying it.
Step 6 : Run It Once
The first run is started by hand, to prove that everything works before it is scheduled. Within one to two minutes it registers your account, proves control of your names, obtains the SSL Certificate, saves it in your bucket and installs it in each store you chose. Its log confirms at the end that every SSL Certificate is current and installed. If it fails instead, fix the cause and run it again, which harms nothing.
Step 7 : Schedule It Daily
The job runs only when something starts it, so the last step is a Cloud Scheduler schedule that starts it once a day. There are two ways to create it, and both work. The easier is the Triggers tab of the job, which fills most of the form in for you. The other is Cloud Scheduler directly. Either way, the service account of the job needs one extra permission on the job itself, which neither form grants, or the schedule fires every day and the job never starts. The guide shows both ways, the permission, and how to test the schedule straight away.
Afterwards
From then on the job runs every day at the hour you chose and reissues each SSL Certificate about thirty days before it expires. The history of the job in Cloud Run shows every run and whether it succeeded.
Adding or removing names is a single edit to the list of domains for that SSL Certificate. The list is the whole list, so the job reissues at once with exactly the names you leave in it, updating the object in Certificate Manager and creating a new numbered resource in the classic Compute store.
A second SSL Certificate is a copy of the block for the first, with its own name and names. A second subscription is a copy of the subscription block with its own three values and a name of its own, and each SSL Certificate that belongs to it carries the number of that block.
Removing a second SSL Certificate or a subscription is deleting its block. The job then stops managing it and deletes nothing, so the object in Google and the files in your bucket stay until you remove them yourself.
Blocks stay numbered in order, so after removing one you renumber the blocks above it, and you point any SSL Certificate that referred to a removed subscription at the one it should use now.
Three things cannot change once the job is set up. The name of each SSL Certificate is kept for good, and the Certificate Manager location and scope are fixed at setup. Everything else is editable through the file.
After any edit, apply the file, then either press Execute on the job or wait for the next daily run. Both pick up the change.
If you add a hostname and use Certificate Manager, the Certificate Map needs a new entry for it. You add that entry by hand in the console, or by running the Certificate Manager installer again with the new hostname, and an entry for a hostname you no longer use stays in the map until you delete it.
The classic Compute store script needs no re-run, because it places the newest resource on the load balancer whatever names are on it.
A new version of the job needs nothing from you, because your job takes each approved update on its next run, as described under Public Container Image.
The Job Configuration File
Everything the job does is decided by the job configuration file, and every line that needs a value of yours has a comment directly above it saying what to put there. Placeholders written in capital letters stand for things only you know, such as your bucket name, the three values of your subscription and your domain names. Lines marked your choice are decisions, such as the store or stores to use and the key type. Every other line stays as it is.
Besides the image, the bucket and the service account, the settings are variables, in a block for each subscription, a block for each SSL Certificate and a block for your provider, plus a few optional ones such as how many days before expiry to reissue. Each variable is listed in the setup guide with the values it accepts. The variables of your provider are the exception, and lego lists those on the page for that provider.
Your own copy of this file is the master. You keep it wherever you keep your own files, and nothing in Google edits it, because the job never reads it again after you apply it. Google keeps only the Cloud Run job built from it, so every later change is an edit to your copy and an apply.
If you lose your copy, you can export the current one from the job. The export brings your settings back, and any value held in Secret Manager returns as a reference rather than the secret itself.
gcloud run jobs describe trustico-caas --region=YOUR-REGION --format export > job.yaml
The command names the job trustico-caas, which is the name the setup uses unless you changed that line, and YOUR-REGION stands for your region. Replace either if yours differ.
Changing a credential kept in Secret Manager is not a change to this file. The file names each secret by its latest version, so a new version is read on the next run, with nothing to edit and nothing to apply. A credential typed directly into the file is a file edit, applied like any other.
The job refuses to start while the directory address, the name of the SSL Certificate, the domain names or the provider code still holds its placeholder, and says which one. It cannot check the External Account Binding (EAB) values of your subscription or the variables of your provider, so copy those exactly. Download The Cloud Run Job Configuration File 🔗
Execution Sequence
Every run follows the same sequence, whether the schedule started it or you did. The job checks its configuration, reads what is in your bucket and decides for each SSL Certificate whether a reissue is due, which by default is when a third of its lifetime remains.
When a reissue is due, the job writes the temporary record in your Domain Name System (DNS), checks it against public resolvers, proves control of your names, obtains the reissued SSL Certificate, saves it in the bucket and installs it in each store you chose. On a day with nothing due it only checks and verifies, and finishes in a few seconds.
The run succeeds when every SSL Certificate is current and installed, and is otherwise recorded as a failed execution. A failed run is not retried the same day, and the next scheduled run starts from scratch.
Installing Each SSL Certificate
The job installs each SSL Certificate in Certificate Manager, the classic Compute store or both, and its work ends there. The Google service that uses the SSL Certificate reads it from that store. If Google refuses an install, the run fails with the message from Google in the log.
Certificate Manager is the recommended store. The job creates one SSL Certificate object there on the first run and updates that same object in place on every reissue, so whatever uses it never needs touching again.
In the classic Compute store, every reissue is a new numbered resource, named after your SSL Certificate with -01, -02 and so on. Whatever uses the SSL Certificate then has to be pointed at the new resource, and a script that runs after each reissue does this for you. Trustico® supplies scripts for load balancers under Optional Extras, and you can write your own for anything else.
Where Keys Live
Your Private Keys never leave your project. The account of your subscription, every SSL Certificate and the Private Key of each one stay in the private bucket from Step 2, in the layout lego uses. The service account of the job can read and write the files in that one bucket and in no other bucket.
With object versioning on, the Private Key and SSL Certificate a reissue replaces are kept as older versions, your way back if a reissue ever has to be undone. Never add or delete anything in the bucket by hand. The job expects to find exactly what it wrote, and a change made by hand can make it issue again when nothing is due, or fail to find its account.
When Something Goes Wrong
A failed run is marked Failed in the history of the job, and the last lines of its log say what went wrong and why. If the job configuration file still holds one of the placeholders the job checks, or a value in the wrong form, the job refuses to start and lists every problem together.
A bucket the job cannot reach or cannot write to points to the bucket name in the job configuration file or the access granted in Step 3. A missing role, or an Application Programming Interface (API) that was never enabled, makes Google refuse the install, and the message from Google names what is missing.
Wrong subscription values show up as an error from lego. Check the three values against what Trustico® supplied with your subscription, two of which are your External Account Binding (EAB) credentials. Learn About External Account Binding (EAB) Credentials 🔗
A Domain Name System (DNS) credential with no rights on the zone, the wrong provider, or a provider variable left as a placeholder also shows up as an error from lego. Check them against the page lego keeps for your provider.
The troubleshooting table in the setup guide quotes each exact line you may meet, with its cause and its fix. Download The Google Cloud ACME Setup Guide File 🔗
Optional Extras
Optional Extras are small scripts from Trustico® that do useful things with the SSL Certificate once the job has installed it. The job runs the same without them. Each one is a single file. Open it, read the instructions at the top, download it, and run it in Cloud Shell. It asks you a few questions, shows you the choices it finds in your project, and changes nothing until you type yes. You can also write your own scripts and do anything you like with the SSL Certificate in your Google Cloud project, on a load balancer, a virtual machine, a Kubernetes cluster or anything else. These are the scripts Trustico® supplies today, and more will follow.
An Alert When a Run Fails
The job does not send a message when a run fails. This script sets up an alert that e-mails you, or notifies you another way you choose, whenever that happens. Download The Alert Script 🔗
The Load Balancer Script for the Classic Compute Store
In the classic Compute store, every reissue is a new SSL Certificate resource, and a load balancer keeps using the old one until it is pointed at the new one. This script does that : every day, after the job, it puts the newest SSL Certificate on your load balancer, and on a day with nothing new it does nothing. Download The Classic Store Load Balancer Script 🔗
The Load Balancer Script for Certificate Manager
With Certificate Manager, a load balancer finds its SSL Certificate through a Certificate Map, which holds one entry per hostname naming the SSL Certificate to use. Because the job updates that SSL Certificate in place, the map is wired once and never changes afterwards for an existing hostname.
You can create those entries yourself, once, in the console under Security, then Certificate Manager, then Certificate Maps, then your Certificate Map, then Add map entry. Done that way, you never need this script at all.
The script is the alternative. It does that same wiring for you, then only checks each day that the entries still point at the SSL Certificate the job keeps up to date.
When you add a hostname to the SSL Certificate, its entry is added the same way the others were, by hand or by running this installer again with the new hostname. An entry for a hostname you no longer use stays in the map until you delete it. Download The Certificate Manager Load Balancer Script 🔗
When Trustico® Publishes an Update
From time to time Trustico® publishes an update. What it means for you depends on the part being updated, and in most cases it means nothing at all.
The job needs nothing from you. It takes the new build on its next run and prints the version on the first line of its log.
The job configuration file is not something you download again. The published file is only the template for a new setup, so you keep using your own copy. If a setting is ever added, it is an edit to that copy and an apply, and the guide will say so at the time.
For the two load balancer scripts, download the installer again and run it again with the same answers. It fetches the newest script each time it runs, redeploys it, and leaves the schedule and anything that already matches as it is. It never deletes.
Running the failed run alert script again changes nothing, and it reports that the alert already exists. To change the alert, delete the old one under Monitoring, Alerting, Policies and run the script again.
For what the job is, who it suits and how it sits beside the other ways to use a Certificate as a Service (CaaS) subscription, see the information page. Learn About Google Cloud SSL Certificate Automation 🔗
Wildcard
Wildcard
Wildcard
