Manually creating Satellite locations

You can create Satellite locations for each place that you like, such as your company's ports in the north and south of the country. A Satellite location represents a data center that you fill with your own infrastructure resources to run your own workloads and IBM Cloud services.

Do not reuse the same name for multiple locations, even after the other location is deleted. If you use the same name 5 times or more within 7 days, you might reach the Let's Encrypt Duplicate Certificate rate limit.

Manually creating locations from the console

Use the Satellite console to create your location.

Before you begin:

Find out more about locations and hosts.
Plan your infrastructure.
Verify your host setup.
Make sure that you have the correct permissions to create locations. For more information, see Checking user permissions.
Satellite uses Object Storage to store data about your location and backups for your location's clusters. You can choose to have a bucket created automatically when you create your location or specify an existing bucket. If you want to use an existing bucket, it must have cross-regional resiliency.

To create a location, open the Satellite console and select Create location.

Getting started options

The following options determine your installation process.

If your infrastructure is on prem or edge, select the On prem and Edge option. With this option, you create a location, choose your zones, and download a host attach script to run on your hosts.

If your infrastructure is a cloud provider and you want to use only hosts that are running RHEL, select the cloud provider that you want to use, enter your credentials, and create your location. You can also download the terraform template and edit it before you run it.

If your infrastructure is a cloud provider and you want to use hosts that are running RHCOS or want to have more control over your host creation, then select Advanced configuration. With this option, you create a location, choose your zones, include your cloud provider credentials, and then download a host attach script (RHEL) or an ignition script (RHCOS) to run on your hosts.

If you selected On prem and Edge, you can change your location options by clicking Edit.

Satellite location options

The following options define your location.

Name: The Satellite location name must start with a letter, can contain letters, numbers, periods (.), and hyphen (-), and must be 35 characters or fewer. Do not reuse the same name for multiple locations, even if you deleted another location with the same name.

Resource group: Resource groups organize your account resources in customizable groupings so that you can quickly assign users access to more than one resource at a time. This value is set to default by default.

Description and Tags: Descriptions and tags help you organize your IBM Cloud resources.

Managed from: The IBM Cloud region that you want to use to manage your location. For more information about why you must select an IBM Cloud region, see About IBM Cloud regions for Satellite. Make sure to select the region that is closest to where your host machines physically reside that you plan to attach to your Satellite location to ensure low network latency between your Satellite location and IBM Cloud.

Zones: The names of the zones must match exactly the names of the corresponding zones in your infrastructure provider where you plan to create hosts, such as a cloud provider zone or on-prem rack. To retrieve the name of the zone for other cloud providers, consult your infrastructure provider.
- Alibaba regions and zones, such as us-east-1a and us-east-1b.
- AWS regions and zones, such as us-east-1a, us-east-1b, and us-east-1c.
- Azure topology.kubernetes.io/zone labels, such as eastus-1, eastus-2, and eastus-3. Don't use only the location name (eastus) or the zone number (1).
- GCP regions and zones, such as us-west1-a, us-west1-b, and us-west1-c.

Red Hat CoreOS Support: Satellite supports hosts that are running either RHEL or RHCOS. For more information, see Planning your operating system.

Object Storage: The exact name of an existing IBM Cloud Object Storage bucket that you want to use to back up Satellite location control plane data. Otherwise, a new bucket is automatically created in an Object Storage instance in your account. Do not delete your Object Storage instance or this bucket. If the service instance or bucket is deleted, your Satellite location control plane data cannot be backed up.

After you click Create, you can attach hosts to your location and finish the setup of your Satellite location control plane. Note that the token in the attach script is an API key, which must be treated and protected as sensitive information.

The host attach script for your location expires one year from the creation date. To make sure that hosts in your location don't have authentication issues, download a new copy of the host attach script at least once per year and update any unassigned hosts. For more information, see Why do my unassigned hosts have an Unresponsive status?.

Want to verify if your location is enabled for Red Hat CoreOS? See Is my location enabled for Red Hat CoreOS?.

Creating locations from the CLI

Use the CLI plug-in for Satellite commands to create your location.

Before you begin

Install the CLI plug-in for Satellite commands.
Make sure that you have the correct permissions to create locations. For more information, see Checking user permissions.
Satellite uses Object Storage to store data about your location and backups for your location's clusters. You can choose to have a bucket created automatically when you create your location or specify an existing bucket. If you want to use an existing bucket, it must have cross-regional resiliency. Don't delete your Object Storage instance or this bucket. If you delete your service instance or bucket, you can't back up your Satellite location control plane data.

To create a Satellite location from the CLI,

Log in to your IBM Cloud account. If you have a federated account, include the --sso option, or create an API key to log in.
```
ibmcloud login [-sso]
```
Create a Satellite location.
```
ibmcloud sat location create --managed-from REGION --name NAME [--cos-bucket COS_BUCKET_NAME] [--description DESCRIPTION] [--ha-zone ZONE1_NAME --ha-zone ZONE2_NAME --ha-zone ZONE3_NAME] [--coreos-enabled] [--logging-account-id LOGGING_ACCOUNT] [--pod-subnet SUBNET] [--pod-network-interface-selection METHOD] [--provider INFRASTRUCTURE_PROVIDER] [--provider-region PROVIDER_REGION] [--provider-credential PATH_TO_PROVIDER_CREDENTIAL] [-q] [--service-subnet SUBNET]
```
--managed-from REGION

Required. The IBM Cloud region, such as wdc or lon, that your Satellite location is managed from. You can use any region, but to reduce latency between IBM Cloud and your location, choose the region that is closest to the compute hosts that you plan to attach to your location later. For a list of supported IBM Cloud regions, see Supported IBM Cloud locations.

--name NAME

Required. Enter a name for your location. The Satellite location name must start with a letter, can contain letters, numbers, periods (.), and hyphen (-), and must be 35 characters or fewer. Do not reuse the same name for multiple locations, even if you deleted another location with the same name.

--cos-bucket COS_BUCKET_NAME

Optional. Enter the name of the IBM Cloud Object Storage bucket that you want to use to back up Satellite location control plane data. Otherwise, a new bucket is automatically created in your Object Storage instance.

Do not delete your Object Storage instance or this bucket. If the service instance or bucket is deleted, your Satellite location control plane data cannot be backed up.

--description DESCRIPTION

Optional. A description of the Satellite location.

--ha-zone ZONE1_NAME --ha-zone ZONE2_NAME --ha-zone ZONE3_NAME
Specify three names for high availability zones in your location. The names of the zones must match exactly the names of the corresponding zones in your infrastructure provider where you plan to create hosts, such as a cloud provider zone or on-prem rack. To retrieve the name of the zone, consult your infrastructure provider.
1. Alibaba regions and zones, such as us-east-1 and us-west-1.
2. AWS regions and zones, such as us-east-1a, us-east-1b, us-east-1c.
3. Azure topology.kubernetes.io/zone labels, such as eastus-1, eastus-2, and eastus-3. Do not use only the location name (eastus) or the zone number (1).
4. GCP regions and zones, such as us-west1-a, us-west1-b, and us-west1-c.
Optional: If you use this option, zone names must be specified in three repeated options. If you do not use this option, the zones in your location are assigned names, such as zone-1.

--coreos-enabled

Optional. Enable Red Hat CoreOS features within the Satellite location. This action cannot be undone.

--logging-account-id LOGGING_ACCOUNT

Optional. The IBM Cloud account ID with the instance of IBM Log Analysis that you want to forward your Satellite logs to. This option is available only in select environments.

--pod-subnet SUBNET

Optional. Specify a custom subnet CIDR to provide private IP addresses for pods. This option can be used only if you also enable Red Hat CoreOS with the --coreos-enabled option. All pods that are deployed to a worker node are assigned a private IP address in the 172.16.0.0/16 range by default. You can avoid subnet conflicts with the network that you use to connect to your location by specifying a custom subnet CIDR that provides the private IP addresses for your pods.

When you choose a subnet size, consider the size of the cluster that you plan to create and the number of worker nodes that you might add in the future. The subnet must have a CIDR of at least /23, which provides enough pod IPs for a maximum of four worker nodes in a cluster. For larger clusters, use /22 to have enough pod IP addresses for eight worker nodes, /21 to have enough pod IP addresses for 16 worker nodes, and so on.
The subnet that you choose must be within one of the following ranges.The subnet that you choose must be within one of the following ranges.
- 172.16.0.0 - 172.17.255.255
- 172.21.0.0 - 172.31.255.255
- 192.168.0.0 - 192.168.254.255
- 198.18.0.0 - 198.19.255.255
Note that the pod and service subnets can't overlap. The service subnet is in the 172.20.0.0/16 range by default. This value can't be set to the value of the related location's pod-subnet or service-subnet.

--service-subnet SUBNET

Optional. Specify a custom subnet CIDR to provide private IP addresses for services. This option can be used only if you also enable Red Hat CoreOS with the --coreos-enabled option. All services that are deployed to the cluster are assigned a private IP address in the 172.20.0.0/16 range by default. You can avoid subnet conflicts with the network that you use to connect to your location by specifying a custom subnet CIDR that provides the private IP addresses for your services.
The subnet must be specified in CIDR format with a size of at least /24, which allows a maximum of 255 services in the cluster, or larger. The subnet that you choose must be within one of the following ranges.
- 172.16.0.0 - 172.17.255.255
- 172.20.0.0 - 172.31.255.255
- 192.168.0.0 - 192.168.254.255
- 198.18.0.0 - 198.19.255.255
Note that the pod and service subnets can't overlap. The pod subnet is in the 172.16.0.0/16 range by default. This value can't be set to the value of the related location's pod-subnet or service-subnet.

--pod-network-interface-selection METHOD
Optional. The method for selecting the node network interface for the internal pod network. The available methods are can-reach and interface. This option can be used only if you also enable Red Hat CoreOS with the --operating-system option.
- To provide a direct URL or IP address, specify can-reach=<url> or can-reach=<ip_address>. If the network interface can reach the provided URL or IP address, this option is used. For example, use can-reach=www.exampleurl.com for specifying a URL and can-reach=172.19.0.0 for specifying an IP address.
- To choose an interface with a Regex string, specify interface=<regex_string>; for example, interface=eth.*
--provider INFRASTRUCTURE_PROVIDER

Optional. The name of the infrastructure provider to create the Satellite location in. Accepted values are aws, azure, gcp, and vmware. If you include this option, you must also include the --provider-credential option.

--provider-region PROVIDER_REGION

Optional. The name of the region in the infrastructure provider where you plan to create all the hosts for the Satellite location, such as us-east-1 in AWS. Consult your infrastructure provider for the region name. If you include this option, you must also include the --provider option.

--provider-credential PATH_TO_PROVIDER_CREDENTIAL

Optional. The path to a JSON file on your local machine that has the credentials of the infrastructure provider for the Satellite location. The credential format is provider-specific. For more information, see Providing Satellite with credentials to your infrastructure provider. If you include this option, you must also include the --provider option.

-q

Optional. Do not show the message of the day or update reminders.
Verify that your location is created and wait for the location Status to change to action required. When you create the location, a location management plane is deployed to the region that you selected during location creation. During this process, the Status of the location shows deploying. While the master deploys, you can now attach compute capacity to your location to complete the setup of the Satellite location control plane.
```
ibmcloud sat location ls
```
Example output
```
Name         ID                     Status            Ready   Created        Hosts (used/total)   Managed From   
mylocation   brhtfum2015a6mgqj16g   action required   no      1 minute ago   0 / 3                Washington DC   
```
To finish the setup of your location.
1. Attach compute hosts to your location.
2. Assign these hosts as worker nodes to the Satellite location control plane.

Want to verify if your location is enabled for Red Hat CoreOS? See Is my location enabled for Red Hat CoreOS?.

I created a Satellite location, what's next?

Now that your Satellite location is set up, you are ready to start using IBM Cloud services.

Add compute capacity to your location by attaching more hosts to the location so that you can run Satellite-enabled IBM Cloud service.
Create a Satellite-enabled IBM Cloud service, such as a Red Hat OpenShift cluster. You assign the additional hosts that you previously attached as worker nodes to provide the compute power for the cluster. You can even register existing Red Hat OpenShift clusters to your location to use as deployment targets.
Manage your applications with Satellite Config.
Create Satellite cluster storage templates.
Learn more about the Satellite Link component and how you can use endpoints to manage the network traffic between your location and IBM Cloud.

Need help? Check out Getting support where you can find information about cloud status, issues, and logging; contacting support; and setting your email notification preferences for IBM Cloud platform-related items.