Attaching AWS hosts to Satellite

Adding AWS hosts to Satellite

You can create your IBM Cloud Satellite location by using hosts that you added from Amazon Web Services (AWS) cloud.

All hosts that you want to add must meet the general host requirements, such as the RHEL 8 packages and networking setup. For more information, see Host requirements.

If you want to use Red Hat CoreOS (RHCOS) hosts in your location, provide your Red Hat CoreOS image file to your Amazon account. For more information, see Importing a VM as an image using. To find RHCOS images, see the list of available images. Note that you must use at least version 4.9.

Before you begin, create a Satellite location.

1. From the Satellite console, select the location where you want to add AWS hosts.

2. Retrieve the host registration script that you must run on your hosts to make them visible to your IBM Cloud Satellite location.

   1. From the Hosts tab, click Attach host.
   2. Optional: Enter any host labels that are used later to automatically assign hosts to Satellite-enabled IBM Cloud services in the location. Labels must be provided as key-value pairs, and must match the request from the service. For example, you might have host labels such as env=prod or service=database. By default, your hosts get a cpu, os, and memory label, but you might want to add more to control the auto assignment, such as env=prod or service=database.
   3. Enter a file name for your script or use the name that is generated for you.
   4. Click Download script to generate the host script and download the script to your local machine. Note that the token in the script is an API key, which should be treated and protected as sensitive information.

3. RHEL only Open the registration script. After the API_URL line, add a section to pull the required RHEL packages with the subscription manager.

   # Enable AWS RHEL package updates
   yum update -y
   yum-config-manager --enable '*'
   yum repolist all
   yum install container-selinux -y
   echo "repos enabled"
   

4. From the AWS EC2 dashboard, go to Instances > Launch Templates.

5. Click Create Launch template and enter the template details as follows.

   For an overview of available options that you can specify in your launch template, see the AWS documentation

   1. Enter a name for your launch template.
   2. In the Amazon machine image (AMI) section, make sure to select a supported Red Hat Enterprise Linux 8 operating system that you can find by entering the AMI ID. You can match AMI IDs and the proper Red Hat Enterprise Linux version by referring to the Red Hat Enterprise Linux AMI Available on Amazon Web Services documentation. If you are creating an Red Hat CoreOS host, you must provide the image to AWS. For more information, see Importing a VM as an image using.
   3. From the Instance type section, select one of the supported AWS instance types.
   4. From the Key pair (login) section, select the .pem key that you want to use to log in to your machines later. If you do not have a .pem key, create one.
   5. In the Network settings, select Virtual Private Cloud (VPC) and an existing subnet and a security group that allows network traffic as defined in Security group settings. If you do not have a subnet or security group that you want to use, create one.
   6. In the Storage (volumes) section, expand the default root volume and update the size of the boot volume to a minimum of 100 GB. Add a second disk with at least 100 GB capacity. For more information about storage requirements, see Host storage and attached devices.
   7. Expand the Advanced details and go to the User Data field.
   8. Enter the host registration script that you modified earlier. If you are adding an RHCOS host, add the ignition script.
   9. Click Create launch template.

6. From the Launch Templates dashboard, find the template that you created.

7. From the Actions menu, select Launch instance from template.

8. Enter the number of instances that you want to create and click Launch instance from template.

9. Wait for the instance to launch. During the launch of your instance, the registration script runs automatically. This process takes a few minutes to complete.

10. Monitor the progress of the registration script.

    1. From the EC2 Instances dashboard, retrieve the public IP address of your instance.
    2. Log in to your instance.

       ssh -i <key>.pem ec2-user@<public_IP_address>
       

    3. Review the status of the registration script.

       journalctl -f -u ibm-host-attach
       

11. Check that your hosts are shown in the Hosts tab of your Satellite console. All hosts show a Health status of Ready when a connection to the machine can be established, and a Status of Unassigned as the hosts are not yet assigned to your Satellite location control plane or a Red Hat OpenShift on IBM Cloud cluster.

12. Assign your AWS hosts to the Satellite control plane or a Red Hat OpenShift on IBM Cloud cluster.

Manually attaching AWS instances with the CLI

You can use the AWS ClI to run your EC2 instances and attach them to your Satellite location. For more information, see the aws ec2 run-instances command reference.

Example command to run AWS EC2 instances.

aws ec2 run-instances --count COUNT --instance-type INSTANCE-TYPE --launch-template LaunchTemplateName=AWS-LAUNCH-TEMPLATE --user-data file://ATTACH-SCRIPT-LOCATION 

AWS instance types

Review the following suggested AWS EC2 instance types that you can use as hosts in IBM Cloud Satellite. You can use other AWS instance types as long as they meet the minimum host requirements for Satellite.

Security group settings for AWS

As described in the host networking requirements, your AWS hosts must have access to connect to IBM Cloud Satellite. If you use hosts in a virtual private cloud (VPC), you can create a security group similar to the following example. You can get the owner, group, user, and VPC IDs from your AWS provider resources.

The following example is a security group that you might create for AWS.

{
	"Description": "Security group for IBM Cloud Satellite hosts",
	"GroupName": "Satellite",
	"IpPermissions": [{
			"FromPort": 80,
			"IpProtocol": "tcp",
			"IpRanges": [{
				"CidrIp": "0.0.0.0/0"
			}],
			"Ipv6Ranges": [],
			"PrefixListIds": [],
			"ToPort": 80,
			"UserIdGroupPairs": []
		},
		{
			"FromPort": 30000,
			"IpProtocol": "tcp",
			"IpRanges": [{
				"CidrIp": "0.0.0.0/0"
			}],
			"Ipv6Ranges": [{
				"CidrIpv6": "::/0"
			}],
			"PrefixListIds": [],
			"ToPort": 32767,
			"UserIdGroupPairs": []
		},
		{
			"IpProtocol": "-1",
			"IpRanges": [],
			"Ipv6Ranges": [],
			"PrefixListIds": [],
			"UserIdGroupPairs": [{
				"GroupId": "<group_ID>",
				"UserId": "<user_ID>"
			}]
		},
		{
			"FromPort": 22,
			"IpProtocol": "tcp",
			"IpRanges": [{
				"CidrIp": "0.0.0.0/0"
			}],
			"Ipv6Ranges": [],
			"PrefixListIds": [],
			"ToPort": 22,
			"UserIdGroupPairs": []
		},
		{
			"FromPort": 30000,
			"IpProtocol": "udp",
			"IpRanges": [{
				"CidrIp": "0.0.0.0/0"
			}],
			"Ipv6Ranges": [{
				"CidrIpv6": "::/0"
			}],
			"PrefixListIds": [],
			"ToPort": 32767,
			"UserIdGroupPairs": []
		},
		{
			"FromPort": 443,
			"IpProtocol": "tcp",
			"IpRanges": [{
				"CidrIp": "0.0.0.0/0"
			}],
			"Ipv6Ranges": [{
				"CidrIpv6": "::/0"
			}],
			"PrefixListIds": [],
			"ToPort": 443,
			"UserIdGroupPairs": []
		}
	],
	"OwnerId": "<owner_ID>",
	"GroupId": "<group_ID>",
	"IpPermissionsEgress": [{
		"IpProtocol": "-1",
		"IpRanges": [{
			"CidrIp": "0.0.0.0/0"
		}],
		"Ipv6Ranges": [],
		"PrefixListIds": [],
		"UserIdGroupPairs": []
	}],
	"VpcId": "<vpc_ID>"
}

For more information, see Control traffic to resources using security groups in the AWS documentation.

I added hosts to my location, what's next?

Now that you added hosts to your location, you can assign them to your location control plane or to your IBM Cloud services.

1. Assign hosts to the location control plane or to your IBM Cloud services.
2. Create a Satellite-enabled IBM Cloud service, such as a Red Hat OpenShift cluster. You can even register existing Red Hat OpenShift clusters to your location to use as deployment targets.
3. Manage your applications with Satellite Config.
4. Create Satellite cluster storage templates.
5. 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.