Connection to AWS
Create and manage connections and resources describes the wizards that create a connection. The following information covers details specific to AWS cloud environments.
Note:
Before creating a connection to AWS, you need to first finish setting up your AWS account as a resource location. See AWS cloud environments.
Create a connection
When you create a connection from Web Studio:
- You must provide the API key and secret key values. You can export the key file containing those values from AWS and then import them. You must also provide the region, availability zone, VPC name, subnet addresses, domain name, security group names, and credentials.
- The credentials file for the root AWS account (retrieved from the AWS console) is not formatted the same as credentials files downloaded for standard AWS users. Therefore, Citrix Virtual Apps and Desktops management cannot use the file to populate the API key and secret key fields. Ensure that you are using AWS Identity Access Management (IAM) credentials files.
Note:
After you create a connection, attempts to update the API key and secret key might fail. To resolve the issue, check your proxy server or firewall restrictions and ensure that the following address is contactable:
https://*.amazonaws.com.
Host connection default values
When you create host connections in AWS cloud environments, the following default values are displayed:
| Option | Absolute | Percentage |
|---|---|---|
| Simultaneous actions (all types) | 125 | 100 |
| Maximum new actions per minute | 125 |
MCS supports 100 maximum concurrent provisioning operations by default.
Service endpoint URL
Standard zone service endpoint URL
When you use MCS, a new AWS connection is added with an API key and an API secret. With this information, along with the authenticated account, MCS queries AWS for the supported zones using the AWS DescribeRegions EC2 API call. The query is made using a generic EC2 Service Endpoint URL https://ec2.amazonaws.com/. Use MCS to select the zone for the connection from the list of supported zones. The preferred AWS service endpoint URL is automatically selected for the zone. However, after you create the service endpoint URL, you can no longer set or modify the URL.
Define IAM permissions
Use the information in this section to define IAM permissions for Citrix Virtual Apps and Desktops on AWS. Amazon’s IAM service permits accounts having multiple users, which can be further organized into groups. These users can possess different permissions to control their ability to perform operations associated with the account. For more information about IAM permissions, see the IAM JSON policy reference.
To apply IAM permissions policy to a new group of users:
- Log in to the AWS management console and select the IAM service from the drop-down list.
- Select Create a New Group of Users.
- Type a name for the new user group and select Continue.
- On the Permissions page, choose Custom Policy. Select Select.
- Type a name for the Permissions policy.
- In the Policy Document section, enter the relevant permissions.
After entering the policy information, selectContinue to complete the group of users. Users in the group are granted permissions to perform only those actions that are required for Citrix Virtual Apps and Desktops.
Important:
Use the policy text provided in the example earlier to list the actions that Citrix Virtual Apps and Desktops uses to perform actions within an AWS account without restricting those actions to specific resources. Citrix recommends that you use the example for testing purposes. For production environments, you might choose to add further restrictions on resources.
Set IAM permissions
Set the permissions in the IAM section of the AWS Management Console:
- In the Summary panel, select the Permissions tab.
- Select Add permissions.
In the Add Permissions to screen, grant permissions:
Use the following as an example in the JSON tab:
Tip:
The noted JSON example might not include all the permissions for your environment. See How to Define Identity Access Management Permissions Running Citrix Virtual Apps and Desktops on AWS for more information.
Required AWS permissions
This section contains the complete list of AWS permissions.
Note:
The iam:PassRole permission is needed only for role_based_auth.
Creating a host connection
A new host connection is added using the information from AWS.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:DescribeAvailabilityZones",,
"ec2:DescribeSubnets",
"ec2:DescribeVpcs"
"ec2:DescribeRegions",
],
"Effect": "Allow",
"Resource": "*"
}
]
}
<!--NeedCopy-->
Power management of VMs
VMs are powered on or off.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:DescribeInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:RebootInstances"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
<!--NeedCopy-->
Creating, updating, or deleting VMs
A machine catalog is created, updated, or deleted with VMs provisioned as AWS instances.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:AttachVolume",
"ec2:AssociateIamInstanceProfile",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateImage",
"ec2:CreateLaunchTemplate",
"ec2:CreateSecurityGroup",
"ec2:CreateTags",
"ec2:CreateVolume",
"ec2:DeleteVolume",
"ec2:DescribeAccountAttributes",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeIamInstanceProfileAssociations",
"ec2:DescribeImages",
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:DescribeLaunchTemplates",
"ec2:DescribeLaunchTemplateVersions",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeRegions",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSnapshots",
"ec2:DescribeSubnets",
"ec2:DescribeTags",
"ec2:DescribeVolumes",
"ec2:DescribeVpcs",
"ec2:DetachVolume",
"ec2:DisassociateIamInstanceProfile",
"ec2:RunInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:TerminateInstances"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"ec2:CreateSecurityGroup",
"ec2:DeleteSecurityGroup",
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"ebs:StartSnapshot",
"ebs:GetSnapshotBlock",
"ebs:PutSnapshotBlock",
"ebs:CompleteSnapshot",
"ebs:ListSnapshotBlocks",
"ebs:ListChangedBlocks",
"ec2:CreateSnapshot"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
<!--NeedCopy-->
Note:
The EC2 section related to security groups is only needed if an isolation security group must be created for the preparation VM during catalog creation. Once this is done, these permissions are not required.
Direct disk upload and download
Direct disk upload eliminates the volume worker requirement for machine catalog provisioning, and instead uses public APIs provided by AWS. This functionality reduces the cost associated with extra storage accounts and the complexity for maintaining volume worker operations.
Note:
The support for volume worker is deprecated.
The following permissions must be added to the policy:
ebs:StartSnapshotebs:GetSnapshotBlockebs:PutSnapshotBlockebs:CompleteSnapshotebs:ListSnapshotBlocksebs:ListChangedBlocksec2:CreateSnapshotec2:DeleteSnapshotec2:DescribeLaunchTemplates
Important:
- You can add a VM to existing machine catalogs without any volume worker operation such as volume worker AMI, and volume worker VM.
- If you delete an existing catalog that used volume worker before, all artifacts including volume worker related are deleted.
EBS encryption of created volumes
EBS can auto-encrypt newly created volumes if the AMI is encrypted, or EBS is configured to encrypt all new volumes. However, to implement the functionality, the following permissions must be included in the IAM policy.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:CreateGrant",
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKeyWithoutPlainText",
"kms:ReEncryptTo",
"kms:ReEncryptFrom"
],
"Resource": "*"
}
]
}
<!--NeedCopy-->
Note:
The permissions can be limited to specific keys by including a Resource and Condition block at the discretion of the user. For example, KMS Permissions with Condition:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:CreateGrant",
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKeyWithoutPlainText",
"kms:ReEncryptTo",
"kms:ReEncryptFrom"
],
"Resource": [
"arn:aws:kms:us-east-2:123456789012:key/abcd1234-a123-456d-a12b-a123b4cd56ef"
],
"Condition": {
"Bool": {
"kms:GrantIsForAWSResource": true
}
}
}
]
}
<!--NeedCopy-->
The following key policy statement is the entire default key policy for KMS keys that is required to allow the account to use IAM policies to delegate permission for all actions (kms:*) on the KMS key.
{
"Sid": "Enable IAM policies",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": "kms:",
"Resource": ""
}
<!--NeedCopy-->
For more information, see AWS Key Management Service official documentation.
IAM role-based authentication
The following permissions are added to support role-based authentication.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::*:role/*"
}
]
}
<!--NeedCopy-->
Minimal IAM permissions policy
The following JSON can be used for all currently supported features. You can create host connections, create, update, or delete VMs, and do power management using this policy. The policy can be applied to the users as explained in Define IAM permissions sections or you can also use role-based authentication using role_based_auth security key and secret key.
Important:
To use role_based_auth, first configure the desired IAM role on all Delivery Controllers in our site. Using Web Studio, add the hosting connection and supply the role_based_auth for the authentication key and secret. A hosting connection with these settings then uses role-based authentication.
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"ec2:AttachVolume",
"ec2:AssociateIamInstanceProfile",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateImage",
"ec2:CreateLaunchTemplate",
"ec2:CreateNetworkInterface",
"ec2:CreateTags",
"ec2:CreateVolume",
"ec2:DeleteLaunchTemplate",
"ec2:DeleteNetworkInterface",
"ec2:DeleteSecurityGroup",
"ec2:DeleteSnapshot",
"ec2:DeleteTags",
"ec2:DeleteVolume",
"ec2:DeregisterImage",
"ec2:DescribeAccountAttributes",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeIamInstanceProfileAssociations",
"ec2:DescribeImages",
"ec2:DescribeInstances",
"ec2:DescribeInstanceTypes",
"ec2:DescribeLaunchTemplates",
"ec2:DescribeLaunchTemplateVersions",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeRegions",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSnapshots",
"ec2:DescribeSubnets",
"ec2:DescribeTags",
"ec2:DescribeVolumes",
"ec2:DescribeVpcs",
"ec2:DetachVolume",
"ec2:DisassociateIamInstanceProfile",
"ec2:RebootInstances",
"ec2:RunInstances",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:TerminateInstances"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"ec2:CreateSecurityGroup",
"ec2:DeleteSecurityGroup",
],
"Effect": "Allow",
"Resource": "*"
},
{
"Action": [
"ebs:StartSnapshot",
"ebs:GetSnapshotBlock",
"ebs:PutSnapshotBlock",
"ebs:CompleteSnapshot",
"ebs:ListSnapshotBlocks",
"ebs:ListChangedBlocks",
"ec2:CreateSnapshot"
],
"Effect": "Allow",
"Resource": "*"
},
{
"Effect": "Allow",
"Action": [
"kms:CreateGrant",
"kms:Decrypt",
"kms:DescribeKey",
"kms:GenerateDataKeyWithoutPlainText",
"kms:GenerateDataKey",
"kms:ReEncryptTo",
"kms:ReEncryptFrom"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "arn:aws:iam::*:role/*"
}
]
}
<!--NeedCopy-->
Note:
- The EC2 section related to SecurityGroups is only needed if an Isolation Security Group must be created for the Preparation VM during catalog creation. Once this is done, these permissions are not required.
- The KMS section is only required when using EBS volume encryption.
- The iam:PassRole permission section is needed only for role_based_auth.
- Specific resource-level permissions can be added instead of full access based on your requirements and environment. Refer to AWS documents Demystifying EC2 Resource-Level Permissions and Access management for AWS resources for more details.
Validate permissions on host connection
You can validate permissions on a host connection to do tasks related to creating and managing MCS machine catalogs. This implementation helps you to find out the missing permissions required for different scenarios such as creating, deleting, and updating VMs, power management of VMs, and EBS encryption, ahead of time so that you can avoid being blocked at critical times.
You can validate the permissions on a host connection using the PowerShell command Test-HypHypervisorConnection. The result from the command is captured as a list where each item in the list is broken into three sections.
- Category: The action or task a user can do to create and manage an MCS machine catalog.
- Corrective Action: The step an admin must do to resolve a users’ missing permissions discrepancy.
- Missing permission: The list of missing permissions for a category.
To validate the permissions, do the following:
- Create a host connection to AWS.
- Open a PowerShell window from the Delivery Controller host.
- Run
asnp citrix*to load the Citrix-specific PowerShell modules. -
Run the following command to verify if you have the required permissions to look up your permissions.
Test-HypHypervisorConnection -LiteralPath "XDHyp:\Connections\AWSCon" <!--NeedCopy--> -
After you add the missing permissions required to look up your permissions, run the following command to verify if you have permissions in the following categories:
- Create Update delete
- Power Management
- EBS encryption
Test-HypHypervisorConnection -LiteralPath "XDHyp:\Connections\AWSCon" [-SecurePassword -Password] "password" -UserName "" -CustomProperties "" <!--NeedCopy-->
For more information on adding permissions, see Set IAM permissions.
Where to go next
- If you’re in the initial deployment process, see Create machine catalogs
- For AWS specific information, see Create an AWS catalog