create satellite location

Creating a Satellite location

The first step to getting started with Satellite is to create a Satellite location. A Satellite location is a representation of an environment in your infrastructure provider, such as an on-prem data center or cloud. Locations are made up of compute sources, called hosts, from separate zones of your backing infrastructure environment.

The type of location that you create dictates the type of operating systems that can run on your hosts. If your location is RHCOS enabled, then you can attach hosts that are running either RHEL and RHCOS. If your location isn't RHCOS enabled, then you can attach only hosts that are running RHEL. You can check whether your location is RHCOS enabled. Create location overview

Before you create your location, check out the following topics.

Find out more about locations and hosts.
Plan your infrastructure.
Verify your host setup.

Automating your location setup with a Schematics template

Automate your setup with templates that use IBM Cloud® Schematics to create a Satellite location, provision hosts in a cloud provider, and set up the Satellite location control plane for you.

To create a location that is enabled for Red Hat CoreOS, you must create your location manually.

For IBM Cloud Satellite to perform actions on your behalf in a cloud provider, you must provide credentials to the cloud provider. The credentials that you provide are stored and encrypted in etcd of the Satellite location control plane master. For more information, see Securing your data.

You can set up Satellite locations with a Schematics template for the following cloud providers.

AWS
Azure
GCP

If you are using this template for demonstration purposes, do not assign all your hosts to your control plane. Hosts that are assigned to the control plane cannot be used for other purposes, such as worker nodes for your cluster. For more information, see Understanding Satellite locations.

What's next?

The Schematics template helped with the initial creation, but you are in control for subsequent location management actions, such as attaching more hosts, creating Satellite clusters, or scaling the Satellite location control plane. If you remove your Satellite location, make sure to remove your workspace in Schematics, too. 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. Manually creating locations from the console

Use the Satellite console to create your location.

Before you begin:

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. 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.

From the Satellite console, click Create location.

Click Advanced configuration.

In the Infrastructure type section, select On-premises or Public cloud. If your infrastructure is in a Public cloud, you can select your Cloud provider. Or, you can select Other cloud for a general setup.

In the Workflow section, select Manual.

If you selected a cloud provider, enter your credentials.

In the Satellite location section, review the following details. To change any of the default values, click Edit.

    For 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.

    The Resource group is set to default by default.

    The Description and Tags fields are optional, and are metadata to help you organize your IBM Cloud resources.

    In the Managed from menu, select the IBM Cloud region that you want to use to manage your location. Red Hat CoreOS is available in all supported Satellite locations and for Red Hat OpenShift version 4.9 and later. Red Hat CoreOS hosts don't support all services. For more information, see Supported Satellite-enabled IBM Cloud services. 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.

    For 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, 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.

    Select Enable CoreOS to create a location that is enabled for Red Hat CoreOS. For more information, see Planning your operating system.

In the Object Storage section, you can click Edit to optionally enter 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.

In the Summary panel, review your order details, and then click Create location. When you create the location, a location control plane master is deployed to one of the zones that are located in the IBM Cloud region that you selected.

Continue with attaching hosts to your location and then 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 COSBUCKETNAME

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 ZONE1NAME --ha-zone ZONE2NAME --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.

    Alibaba regions and zones, such as us-east-1 and us-west-1.
    AWS regions and zones, such as us-east-1a, us-east-1b, us-east-1c.
    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).
    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. 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 PATHTOPROVIDER_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 control plane master 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.
    Attach compute hosts to your location.
    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?. Is my location enabled for Red Hat CoreOS?

You can verify that your location is enabled for Red Hat CoreOS by running the location get command. Look for the Ignition Server Port: field to populate. Wait to check until after your location is provisioned.

Red Hat CoreOS is available in all supported Satellite locations and for Red Hat OpenShift version 4.9 and later. Red Hat CoreOS hosts don't support all services. For more information, see Supported Satellite-enabled IBM Cloud services.

ibmcloud sat location get --location LOCATION

Example output

Name: my-coreos-test
ID: <ID>
Created: 2022-03-26 15:02:00 +0000 (4 days ago)
Managed From: dal
State: action required
Ready for deployments: no
Message: R0012: The location control plane does not have hosts in all 3 zones. Add available hosts to your location for the control plane.
Hosts Available: 0
Hosts Total: 0
Host Zones: us-south-1, us-south-2, us-south-3
Provider: -
Provider Region: -
Provider Credentials: no
Public Service Endpoint URL: <ENDPOINT>
Private Service Endpoint URL: -
OpenVPN Server Port: -
Ignition Server Port: 30119
Konnectivity Server Port: 32157

To create a Red Hat CoreOS-enabled location, see Manually creating Satellite locations. 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.