Before you begin
You need the following:- A self-hosted Omni running v1.12.0 or later. Earlier versions can’t read the factory token from a file.
- An Enterprise Image Factory API token created with the Automation (Omni / Terraform) token actor. To create one, see Manage Enterprise Image Factory Credentials.
- Network access from Omni and from your machines to the Enterprise Image Factory at
https://factory.siderolabs.com. Omni builds schematics and installation media there, and machines pull their installer images from it.
Primary and secondary image factories
Omni can use two image factories:- Primary image factory: Omni uses the primary image factory to create all new schematics, installation media, and installer images. If the image factory requires authentication, as the Enterprise Image Factory does, Omni connects to it with the API token.
- Secondary image factory: An optional image factory that keeps serving the machines installed from it and the Talos versions that only it offers.
factory.talos.dev, set that image factory as the secondary image factory.
The two image factories let Omni migrate existing machines to the Enterprise Image Factory gradually, without upgrading every machine at once.
Each machine moves on its next Talos version or schematic change, if the Enterprise Image Factory serves that Talos version.
Connect Omni to the Enterprise Image Factory
The following steps save the API token to a file, configure the two image factories, check that Omni connects to the Enterprise Image Factory, and rotate the token later.Step 1: Save the token to a file
Omni reads the API token from a file. Save the token you created in Before you begin to a file on the Omni host that only the user running Omni can read:<eif-api-token> with your token.
Omni stops at startup if it can’t read the file.
Step 2: Configure the factories
Set the Enterprise Image Factory and the token file as the primary image factory, and your current image factory as the secondary image factory. If all your machines were installed from the Enterprise Image Factory, leave out the secondary image factory settings. Use Omni flags or the Omni configuration file:- Flags
- Configuration file
When Omni runs in Docker, mount the token file into the container read-only, and pass the factory flags to Omni. Add the following to your
docker run command:- The primary and secondary image factories have the same URL.
- A factory has both a token file and a username and password. Use only the token file.
- The token file can’t be read.
--primary-factory-* settings replace the deprecated --image-factory-address, --image-factory-username, and --image-factory-password flags. When --primary-factory-url is set, Omni ignores the deprecated flags.
For all factory settings, including the optional PXE URLs, see registries.factories in the Omni configuration reference.
Step 3: Check the connection
After Omni restarts, check the factory settings that Omni reports. Run the following command:isenterpriseimagefactory: true shows that Omni uses the Enterprise Image Factory as its primary image factory.
To see which factory each Talos version comes from, run:
imagefactoryurl field of each version shows the factory that Omni uses for it, and isenterprise shows whether that factory is an Enterprise Image Factory.
Step 4: Rotate the token
Omni reads the token file again when it changes, and at least once a minute, so a new token takes effect without a restart. To rotate the token, create a new API token with the Automation (Omni / Terraform) token actor, and write it into the existing file:the image factory token changed when it reads the new token. Then revoke the old token in the Enterprise Image Factory. For more on rotating tokens, see Rotate an API token.