Configure sites and add servers
Sites group multiple AM servers together to provide services.
To configure a site, follow these high-level steps:
-
Install the first server in the site. This creates the configuration that the site will share.
Learn more in Interactive install.
-
Add the first server to a site if you didn’t do this already during the installation.
Learn more in Configure a site with the first server.
-
Add more servers to the site.
Learn more in Add a server to a site.
Configure a site with the first server
The following steps show how to set up a site when AM is running:
-
Review AM’s load balancing requirements in Load balancing.
-
In the AM admin UI, go to Deployment > Sites.
-
Click Add a Site to start configuring the new site.
-
On the New Site page, enter the site name without any spaces. For example, the site name must be in the format
ExampleSite
, rather thanExample Site
.Set the Primary URL to the load balancer URL that’s the entry point for the site, such as
https://lb.example.com/am
.The site URL is the URL to the load balancer in front of the AM servers in the site. For example, if your load balancer listens for HTTPS on host
lb.example.com
and port443
with AM under/am
, then your site URL ishttps://lb.example.com/am
.Client applications and web or Java agents access the servers in the site through the site URL.
-
Click Save to keep the site configuration.
-
Configure the cookie domain of your site as required. Learn more in Change the cookie domain.
-
Go to Deployment > Servers > Server Name > General.
-
Set the Parent Site drop-down menu to the name of the site you just created, and save your changes.
At this point, the first server is part of the new site you have configured.
For all additional servers in the AM site, add them to the site at configuration time as described in Add a server to a site.
Add a server to a site
High availability requires redundant servers in case of failure. With AM, you configure an AM site with multiple servers in a pool behind a load balancing service that exposes a single URL as an entry point to the site.
Follow these steps to configure a server to an existing site:
-
Go to the deployment URL of the new instance to display the AM configurator page.
-
On the initial configuration page, click Create New Configuration.
-
Read the license agreement. Agree to the license agreement and click Continue.
-
On the Default User Password page, enter the same password you entered for the
amAdmin
administrator when you configured the first server in the site. -
Configure server settings as required.
The cookie domain must be identical to that of the first server in the site.
You’ll get a warning if the Configuration Directory isn’t empty. If this happens, check that the directory you’re trying to use doesn’t contain any data you need to preserve. -
On the Configuration Data Store page, configure the same DS instance that is already used as the configuration store for the rest of the instances in the site, including the same encryption key.
Make sure you also select the Additional server for existing deployment option.
-
On the Site Configuration page, select Yes, and enter the same Site Name and Load Balancer URL values as the existing servers in the site.
Spaces aren’t allowed in the site name. -
Check the details on the Configurator Summary page.
-
If anything needs changing, click Previous to return to earlier pages and update as needed.
-
If everything is correct, click Create Configuration to proceed.
-
-
When the configuration process completes, stop the newly-installed AM instance or the container where it runs, and don’t try to access it.
-
Compare the
/path/to/am/config/boot.json
bootstrap file with that of a running instance. Make sure the newly installed instance’s bootstrap file is appropriate for your environment.The
boot.json
file doesn’t exist in the new instanceDepending on the configuration of the AM keystore in the site, the installation process might not create the bootstrap file.
If not, copy the bootstrap file from another instance and continue with the procedure.
Unless your environment has a requirement to configure the AM keystore in a different location on each instance, it’s likely the bootstrap file will be the same across the site.
If you are overriding the start up settings:
-
Make sure you have copied the customized bootstrap file from another instance in the site.
-
Make sure you are overwriting the existing bootstrap file with your modified file prior to every AM restart.
-
-
Make the existing AM keystore infrastructure available to the new instance:
-
Back up the new instance’s default keystore and password files in the following locations:
-
/path/to/am/security/keystores/
-
/path/to/am/security/secrets/default/
-
-
Make sure the existing keystores in the site are available in the same location to the new instance. You might need to make changes, such as copying the keystores and their password files or mounting a volume.
-
Make sure the keystore files configured in the
/path/to/am/config/boot.json
file are available to the instance.
-
-
Make the existing secret store infrastructure in the site available to the new instance:
-
In the AM admin UI of an existing instance in the site, go to Configure > Secret Stores.
-
Review the list of secret stores configured globally and provide the relevant stores to the new instance. For example:
-
For keystore-type secret stores, copy the keystores to the same path on the new instance.
-
For filesystem-type secret stores, copy the contents of the directories to the same path or make the filesystem available on the same mount point on the new instance.
-
For HSM-type stores, make sure the new instance can access it.
-
For secrets configured as environment variables accessible by the container where AM runs, make sure they’re also accessible by the container of the new instance.
-
-
Go to Realms > Realm Name > Secret Stores.
-
Review the list of secret stores configured per realm and make sure to provide the relevant stores to the new instance.
-
-
Restart the new instance.
The instance is now configured for the site.
-
Review AM’s load balancing requirements in Load balancing.
-
Make sure the cookie domain configuration is appropriate for your site. Learn more in Change the cookie domain.