Citrix Virtual Apps and Desktops service

Google Cloud Platform virtualization environments

The Citrix Virtual Apps and Desktops service lets you provision and manage machines on Google Cloud Platform (GCP). This article walks you through using Machine Creation Services (MCS) to provision virtual machines in your Citrix Virtual Apps or Citrix Virtual Desktops service deployment.

Requirements

  • Citrix Cloud account. The feature described in this article is available only in Citrix Cloud.
  • Citrix Virtual Apps and Desktops service subscription. For details, see Get started.
  • A GCP project. The project stores all compute resources associated with the machine catalog. It can be an existing project or a new one.
  • Enable four APIs in your Google Cloud project. For details, see Enable Google Cloud APIs.
  • GCP service account. The service account authenticates to Google Cloud to enable access to the project. For details, see Configure the Google Cloud service account.
  • Enable Google prviate access. For details, see Enable-private-google-access.

Enable Google Cloud APIs

To use the Google Cloud functionality through Citrix Studio, enable these APIs in your Google Cloud project:

  • Compute Engine API
  • Cloud Resource Manager API
  • Identity and Access Management (IAM) API
  • Cloud Build API

From the GCP console, complete these steps:

  1. In the upper left menu, select APIs and Services > Dashboard.

    APIs and Services Dashboard select image

  2. On the Dashboard screen, ensure that Compute Engine API is enabled. If not, follow these steps:

    1. Navigate to APIs and Services > Library.

      APIs and Services Library image

    2. In the search box, type Compute Engine.

    3. From the search results, click Compute Engine API.

    4. On the Compute Engine API page, click Enable.

  3. Enable Cloud Resource Manager API.

    1. Navigate to APIs and Services > Library.

    2. In the search box, type Cloud Resource Manager.

    3. From the search results, click Cloud Resource Manager API.

    4. On the Cloud Resource Manager API page, click Enable. The API’s status appears.

  4. Similarly, enable Identity and Access Management (IAM) API and Cloud Build API.

Configure the Google Cloud service account

A Google Cloud service account lets you create and manage resources inside GCP projects. A Google Cloud service account is required to provision and manage machines, as described in this article. The Google Cloud account authenticates to Citrix Cloud using a key generated by Google Cloud. Each account (personal or service) contains various roles defining the management of the project.

We recommend that you create a new service account. To do so, follow these steps:

  1. In the GCP console, navigate to IAM & Admin > Service accounts.

  2. On the Service accounts page, click CREATE SERVICEACCOUNT.

  3. On the Create service account page, type the required information and then click CREATE.

    Tip:

    You can click CANCEL to save and exit the Service account details page without completing the Grant this service account access to project and the Grant users access to this service account pages. We recommend that you complete the remaining two pages later.

When creating a service account, there is an option to create a key for the account. You need this key when creating a connection in Citrix Studio. The key is contained in a credential file (.json). The file is automatically downloaded and saved to the “Downloads” folder after you create the key. When you create the key, be sure to set the key type to JSON. Otherwise, Studio cannot parse it.

Tip:

Create keys using the Service accounts page in the GCP console. We recommend that you change keys regularly for security purposes. You can provide new keys to the Citrix Virtual Apps and Desktops application by editing an existing GCP connection.

Also, you need to grant your service account the necessary permissions to access your GCP project. To do so, follow these steps:

  1. In the GCP console, navigate to IAM & Admin > IAM.

  2. On the IAM page, locate the service account you created and then click the pencil icon to edit the service account.

  3. On the Edit permissions page, click ADD ANOTHER ROLE to add the following roles to your service account one by one and then click SAVE.

    • Compute Admin
    • Storage Admin
    • Cloud Build Editor
    • Service Account User
    • Cloud Datastore User
  4. Update the roles assigned to your project’s Cloud Build service account.

    1. In the GCP console, navigate to IAM & Admin > IAM.
    2. On the IAM page, locate the Cloud Build service account and then click the pencil icon to edit the service account. You can identify the Cloud Build service account by its user name, which is in this format: <your_gcp_project_ID_number>@cloudbuild.gserviceaccount.com.
    3. On the Edit permissions page, click ADD ANOTHER ROLE to add the following roles to your Cloud Build service account one by one and then click SAVE.
      • Cloud Build Service Account
      • Compute Instance Admin
      • Service Account User

Enable private Google access

When a VM lacks an external IP address assigned to its network interface, packets are only sent to other internal IP addresses destinations. When you enable private access, the VM connects to the set of external IP addresses used by the Google API and associated services. To ensure that a VM in your subnet can access the Google APIs without a public IP address for MCS provisioning:

  1. In GCP, access the VPC network configuration.
  2. In the Subnet details screen, turn on Private Google access.

Private Google access

For more information, see Configuring Private Google Access.

Important:

If your network is configured to prevent VM access to the Internet, ensure that your organization assumes the risks associated with enabling Private Google access for the subnet to which the VM is connected.

Add a connection

In Citrix Studio, follow the guidance in Create a connection and resources. The following description guides you through setting up a hosting connection in Citrix Studio:

  1. On the Manage tab, navigate to Configuration > Hosting in the Studio navigation pane.

  2. In the Actions pane, click Add Connection and Resources.

  3. On the Connection page, select Create a new Connection and Studio tools, and then click Next.

    • Connection type. Select Google Cloud Platform from the menu.
    • Service account key. Import the key contained in your Google credential file (.json). To do so, locate your credential file, open the file with Notepad (or any text editor), and then copy the content. After that, return to the Connection page, click Import key, paste the content, and then click OK.
    • Service account ID. The field automatically populates with the information from the imported key.
    • Connection name. Type a name for the connection.
  4. On the Region page, select a project name from the menu, select a region containing the resources you want to use, and then click Next.

  5. On the Network page, type a name for the resources, select a virtual network from the menu, select a subset, and then click Next. The resource name helps identify the region and network combination in Studio. Virtual networks with the (Shared) suffix appended to their name represent shared VPCs. If you configure a subnet-level IAM role for a shared VPC, only specific subnets of the shared VPC appear on the subnet list.

    Note:

    • The resource name can contain 1–64 characters, and cannot contain only blank spaces or the characters \ / ; : # . * ? = < > | [ ] { } " ' ( ) ' ).
  6. On the Summary page, confirm the information and then click Finish to exit the Add Connection and Resources window.

After creating the connection and resources, Studio lists the connection and resources you created. To configure the connection, select the connection and then click the applicable option in the Actions pane.

Similarly, you can choose to delete, rename, or test the resources created under the connection. To do so, select the resource under the connection and then click the applicable option in the Actions pane.

Prepare a master VM instance and a persistent disk

Tip:

Persistent disk is the GCP term for virtual disk.

To prepare your master VM instance, create and configure a VM instance with properties that match the configuration you want for the cloned VDA instances in your planned machine catalog. The configuration does not apply only to the instance size and type. It also includes instance attributes such as metadata, tags, GPU assignments, network tags, and service account properties.

As part of the mastering process, MCS uses your master VM instance to create the GCP instance template. The instance template is then used to create the cloned VDA instances that comprise the machine catalog. Cloned instances inherit the properties (except the VPC, subnet, and persistent disk properties) of the master VM instance from which the instance template was created.

After configuring the properties of the master VM instance to your specifics, start the instance and then prepare the persistent disk for the instance.

We recommend that you manually create a snapshot of the disk. Doing so lets you use a meaningful naming convention to track versions, gives you more options to manage earlier versions of your master image, and saves time for machine catalog creation. If you do not create your own snapshot, MCS creates one for you. You can use it to create the custom image in your GCP image library.

Create a machine catalog

Note:

Create your resources before you create a machine catalog. Use the naming conventions established by GCP when configuring machine catalogs. See Bucket and object naming guidelines for more information.

In Citrix Studio, follow the guidance in Create machine catalogs. The following description is unique to GCP catalogs.

  1. On the Manage tab, select Machine Catalogs in the Studio navigation pane.

  2. In the Actions pane, click Create Machine Catalog.

  3. On the Operating System page, select Multi-session OS and then click Next.

    • The Citrix Virtual Apps and Desktops service also supports single-session OS.
  4. On the Machine Management page, select the Machines that are power managed and the Citrix Machine Creation Services options and then click Next. If there are multiple resources, select one from the menu.

  5. On the Master Image page, select a VM and the minimum functional level for the catalog and then click Next. If you want to use the sole tenancy functionality, be sure to select an image whose node group property is correctly configured. See Enable sole tenancy.

  6. On the Virtual Machines page, specify how many VMs you want to create, view the detailed specification of the VMs, and then click Next. If you use sole tenant node groups for machine catalogs, be sure to select only the zones where reserved sole tenant nodes are available. See Enable sole tenancy.

  7. On the Computer Accounts page, select an Active Directory account and then click Next.

    • If you select Create new Active Directory accounts, select a domain and then enter the sequence of characters representing the naming scheme for the provisioned VM computer accounts created in Active Directory. The account naming scheme can contain 1–64 characters, and cannot contain blank spaces, or non-ASCII or special characters.
    • If you select Use existing Active Directory accounts, click Browse to navigate to the existing Active Directory computer accounts for the selected machines.
  8. On the Domain Credentials page, click Enter credentials, type the user name and password, click OK, and then click Next.

    • The credential you type must have permissions to perform Active Directory account operations.
  9. On the Scopes page, select scopes for the machine catalog and then click Next.

    • You can select optional scopes or click custom scope to customize scopes as needed.
  10. On the Summary page, confirm the information, specify a name for the catalog, and then click Finish.

    Note:

    The catalog name can contain 1–39 characters, and cannot contain only blank spaces or the characters \ / ; : # . * ? = < > | [ ] { } " ' ( ) ' ).

Machine catalog creation might take a long time to complete. After that, Studio lists the catalog you created. You can verify that the machines are created on the target node groups in the GCP console.

Add machines to a catalog

To add machines to a catalog, follow these steps:

  1. In the Studio navigation pane, select Machine Catalogs.

  2. Select the machine catalog to which you want to add machines.

  3. In the Actions pane, click Add Machines.

  4. On the Virtual Machines page, specify the number of machines you want to add and then click Next.

  5. On the Computer Accounts page, select an Active Directory account and then click Next.

  6. On the Domain Credentials page, click Enter credentials, type the user name and password, click OK, and then click Next.

  7. On the Summary page, confirm the information and then click Finish.

Update machines

This feature can be useful in cases where you want to update your master image or the minimum functional level.

To update machines, follow these steps:

  1. In the Studio navigation pane, select Machine Catalogs.

  2. Select the machine catalog that contains machines you want to update.

  3. In the Actions pane, click Update Machines.

  4. On the Master Image page, select a VM and the minimum functional level for the catalog and then click Next.

  5. On the Rollout Strategy page, specify when you want to update the machines and then click Next.

  6. On the Summary page, confirm the information and then click Finish.

To roll back a machine update, follow these steps:

Important:

Do not rename, delete, or move master images. Otherwise you cannot roll back the update.

  1. In the Studio navigation pane, select Machine Catalogs.

  2. Select the machine catalog where you want to roll back the machine update.

  3. In the Actions pane, click Rollback Machine Update.

  4. On the Overview page, confirm the information and then click Next.

  5. On the Rollout Strategy page, configure the rollout strategy and then click Next.

  6. On the Summary page, confirm the information and then click Finish.

Power management

The Citrix Virtual Apps and Desktops service lets you power manage GCP machines. Use the Search node in the navigation pane to locate the machine you want to power manage. The following power actions are available:

  • Delete
  • Start
  • Restart
  • Force Restart
  • Shut Down
  • Force Shutdown
  • Add to Delivery Group
  • Manage Tags
  • Turn On Maintenance Mode

You can also power manage GCP machines by using Autoscale. To do so, add the GCP machines to a Delivery Group and then enable Autoscale for that Delivery Group. For more information about Autoscale, see Autoscale.

Import manually created GCP machines

You can create a connection to GCP and then create a catalog containing GCP machines. Then, you can manually power cycle GCP machines through Citrix Virtual Apps and Desktops service. With this feature, you can:

  • Import manually created GCP multi-session OS machines into a Citrix Virtual Apps and Desktops machine catalog.
  • Remove manually created GCP multi-session OS machines from a Citrix Virtual Apps and Desktops catalog.
  • Use existing Citrix Virtual Apps and Desktops power management capabilities to power manage GCP Windows multi-session OS machines. For example, set a restart schedule for those machines.

This functionality does not require changes to an existing Citrix Virtual Apps and Desktops provisioning workflow, nor the removal of any existing feature. We recommend that you use MCS to provision machines in Studio instead of importing manually created GCP machines.

Shared Virtual Private Cloud

Shared Virtual Private Clouds (VPCs) comprise a host project, from which the shared subnets are made available, and one or more service projects that use the resource. Shared VPCs are desirable options for larger installations because they provide centralized control, usage, and administration of shared corporate Google cloud resources. For more information, see the Google Documentation site.

With this feature, Machine Creation Services (MCS) supports provisioning and managing machine catalogs deployed to Shared VPCs. This support, which is functionally equivalent to the support currently provided in local VPCs, differs in two areas:

  1. You must grant extra permissions to the Service Account used to create the Host Connection. This process allows MCS to access and utilize Shared VPC Resources.
  2. You must create two firewall rules, one each for ingress and egress. These firewall rules are used during the image mastering process.

New permissions required

A GCP service account with specific permissions is required when creating the host connection. These additional permissions must be granted to any service accounts used to create Shared VPC based host connections.

Tip:

These additional permissions are not new to the Citrix Virtual Apps and Desktops service. They are used to facilitate the implementation of local VPCs. With Shared VPCs, these additional permissions allow access to other shared VPC resources.

A maximum of four extra permissions must be granted to the service account associated with the host connection to support Shared VPC:

  1. compute.firewalls.list - This permission is mandatory. It allows MCS to retrieve the list of firewall rules present on the Shared VPC.
  2. compute.networks.list - This permission is mandatory. It allows MCS to identify the Shared VPC networks available to the service account.
  3. compute.subnetworks.list – This permission is optional depending on how you use VPCs. It allows MCS to identify the subnets within the visible Shared VPCs. This permission is already required when using local VPCs but must also be assigned in the Shared VPC host project.
  4. compute.subnetworks.use - This permission is optional depending on how you use VPCs. It is necessary to use subnet resources in the provisioned machine catalogs. This permission is already required for using local VPCs but must also be assigned in the Shared VPC host project.

When using these permissions, consider that there are different approaches based on the type of permission used to create the machine catalog:

  • Project-level permission:
    • Allows access to all Shared VPCs within the host project.
    • Requires the permissions #3 and #4 must be assigned to the service account.
  • Subnet-level permission:
    • Allows access to specific subnets within the Shared VPC.
    • Permissions #3 and #4 are intrinsic to the subnet level assignment and therefore do not need to be assigned directly to the service account.

Select the approach that matches your organizational needs and security standards.

Tip:

For more information about the differences between project-level and subnet-level permissions, see the Google Cloud documentation.

Firewall Rules

During the preparation of a machine catalog, a machine image is prepared to serve as the master image system disk for the catalog. When this process occurs, the disk is temporarily attached to a virtual machine. This VM must run in an isolated environment that prevents all inbound and outbound network traffic. This is accomplished through a pair of deny-all firewall rules; one for ingress and one for egress traffic. When using GCP local VCPs, MCS creates this firewall in the local network and applies it to the machine for mastering. After mastering completes, the firewall rule is removed from the image.

We recommend keeping the number of new permissions required to use Shared VPCs to a minimum. Shared VPCs are higher-level corporate resources and typically have more rigid security protocols in place. For this reason, create a pair of firewall rules in the host project on the shared VPC resources, one for ingress and one for egress. Assign the highest priority to them. Apply a new target tag to each of these rules, using the following value:

citrix-provisioning-quarantine-firewall

When MCS creates or updates a machine catalog, it searches for firewall rules containing this target tag. It then examines the rules for correctness and applies them to the machine used to prepare the master image for the catalog. If the firewall rules are not found, or the rules are found but the rules or their priorities are incorrect, a message similar to the following appears:

"Unable to find valid INGRESS and EGRESS quarantine firewall rules for VPC <name> in project <project>. " Please ensure you have created 'deny all' firewall rules with the network tag ‘citrix-provisioning-quarantine-firewall' and proper priority." "Refer to Citrix Documentation for details."

Configuring the shared VPC

Before adding the Shared VPC as a host connection in Citrix Studio, complete the following steps to add service accounts from the project you intend to provision into:

  1. Create an IAM role.
  2. Add the service account used to create a CVAD host connection to the Shared VPC host project IAM role.
  3. Add the Cloud Build service account from the project you intend to provision into to the Shared VPC host project IAM role.
  4. Create firewall rules.

Create an IAM role

Determine the role’s access level — project level access or a more restricted model using subnet level access.

Project level access for IAM role. For the project level IAM role, include the following permissions:

  • compute.firewalls.list
  • compute.networks.list
  • compute.subnetworks.list
  • compute.subnetworks.use

To create a project level IAM role:

  1. In the GCP console, navigate to IAM & Admin > Roles.
  2. On the Roles page, click CREATE ROLE.
  3. On the Create Role page, specify the role name. Click ADD PERMISSIONS.
    1. On the Add permissions page, add permissions to the role, individually. To add a permission, type the name of the permission in the Filter table field. Select the permission and then click ADD.
    2. Click CREATE.

Subnet-level IAM role. This role omits the addition of the permissions compute.subnetworks.list and compute.subnetworks.use after selecting CREATE ROLE. For this IAM access level, the permissions compute.firewalls.list and computer.networks.list must be applied to the new role.

To create a subnet level IAM role:

  1. In the GCP console, navigate to VPC network > Shared VPC. The Shared VPC page appears, displaying the subnets of the Shared VPC networks that the host project contains.
  2. On the Shared VPC page, select the subnet that you want to access.
  3. In the top-right corner, click ADD MEMBER to add a service account.
  4. On the Add members page, complete these steps:
    1. In the New members field, type the name of your service account and then select your service account in the menu.
    2. Click the Select a role field and then Compute Network User.
    3. Click SAVE.
  5. In the GCP console, navigate to IAM & Admin > Roles.
  6. On the Roles page, click CREATE ROLE.
  7. On the Create Role page, specify the role name. Click ADD PERMISSIONS.
    1. On the Add permissions page, add permissions to the role, individually. To add a permission, type the name of the permission in the Filter table field. Select the permission, and then click ADD.
    2. Click CREATE.

Add a service account to the host project IAM role

After creating an IAM role, perform the following steps to add a service account for the host project:

  1. In the GCP console, navigate to the host project and then to IAM & Admin > IAM.
  2. On the IAM page, click ADD to add a service account.
  3. On the Add members page:
    1. In the New members field, type the name of your service account and then select your service account in the menu.
    2. Click the Select a role field, type the IAM role you created, and then click the role in the menu.
    3. Click SAVE.

The service account is now configured for the host project.

Add the cloud build service account to the shared VPC

Every Google Cloud subscription has a service account that is named after the project ID number, followed by cloudbuild.gserviceaccount. For example: 705794712345@cloudbuild.gserviceaccount.

You can determine what the project ID number is for your project by selecting Home and Dashboard in the Google Cloud console:

Google Cloud console navigation pane

Find the Project Number below the Project Info area of the screen.

Perform the following steps to add the Cloud Build service account to the Shared VPC:

  1. In the Google Cloud console, navigate to the host project and then to IAM & Admin > IAM.
  2. On the Permissions page, click ADD to add an account.
  3. On the Add members page, complete these steps:
    1. In the New members field, type the name of the Cloud Build service account and then select your service account in the menu.
    2. Click the Select a role field, type Computer Network User, and then click the role in the menu.
    3. Click SAVE.

Create firewall rules

As part of the mastering process, MCS copies the selected machine image and uses it to prepare the master image system disk for the catalog. During mastering, MCS attaches the disk to a temporary virtual machine, which then runs preparation scripts. This VM must run in an isolated environment that prohibits all inbound and outbound network traffic. To create an isolated environment, MCS requires two deny all firewall rules (an ingress rule and an egress rule). Therefore, create two firewall rules in the Host Project as follows:

  1. In the GCP console, navigate to the host project and then to VPC network > Firewall.
  2. On the Firewall page, click CREATE FIREWALL RULE.
  3. On the Create a firewall rule page, complete the following:
    • Name. Type a name for the rule.
    • Network. Select the Shared VPC network to which the ingress firewall rule applies.
    • Priority. The smaller the value is, the higher the priority of the rule is. We recommend a small value (for example, 10).
    • Direction of traffic. Select Ingress.
    • Action on match. Select Deny.
    • Targets. Use the default, Specified target tags.
    • Target tags. Type citrix-provisioning-quarantine-firewall.
    • Source filter. Use the default, IP ranges.
    • Source IP ranges. Type a range that matches all traffic. Type 0.0.0.0/0.
    • Protocols and ports. Select Deny all.
  4. Click CREATE to create the rule.
  5. Repeat steps 1–4 to create another rule. For Direction of traffic, select Egress.

Add a connection

After adding the network interfaces to the Cloud Connector instance, add a connection.

Enable sole tenancy

The Citrix Virtual Apps and Desktops service supports sole tenancy. With sole tenancy, you specify the zones where you want to create VMs in Citrix Studio. To configure sole tenancy, you must complete the following on GCP:

  • Reserve a sole-tenant node
  • Create the VDA master image

Reserving a Google Cloud sole-tenant node

To reserve a sole-tenant node, perform the following steps:

  1. In the Google Cloud console, navigate to Compute Engine > Sole-tenant nodes.

  2. On the Sole-tenant nodes page, click CREATE NODE GROUP.

  3. On the Create a node group page, complete these steps:

    1. Type a name for the node group. For example,mh-sole-tenant-node-group-1.
    2. Select a region. For example, us-east1.
    3. Select a zone where the reserved system resides. For example, us-east1-b.

      We recommend that the region and the zone you select allow access to your domain controllers and the subnets used for provisioning machine catalogs.

    4. Associate a node group with a node template. Perform these steps:

      Important:

      A node template is used to indicate performance characteristics of the system that is reserved in the node group. Those characteristics include the number of vGPUs, the amount of memory allocated to the node, and the machine type used for machines created on the node.

      1. Select Create node template from the drop-down menu. The Create a node template page appears.
      2. On the Create a node template page, configure the required information:

        Name. Type a name for the node template. Node type. From the drop-down menu, select a node type that meets your needs. For more information on node types, see the Google Cloud documentation at https://cloud.google.com/compute/docs/nodes/sole-tenant-nodes#node_types.

      3. Click Create to exit the Create a node template page and to return to the Create a node group page.
  4. Click Create to complete creating a node group.

Creating the VDA master image

To deploy machines on the sole-tenant node successfully, you need to take extra steps when creating a master VM image. Machine instances on GCP have a property called node affinity labels. Instances used as master images for catalogs deployed to the sole-tenant node require a node affinity label that matches the name of the target node group. To achieve this, keep the following in mind:

Note:

If you intend to use sole tenancy with a shared VPC, see Shared Virtual Private Cloud.

Set a node affinity label when creating a new instance

To set the node affinity label:

  1. In the GCP console, navigate to Compute Engine > VM instances.

  2. On the VM instances page, click Create instance.

  3. On the Instance creation page, type or configure the required information and then click management, security, disks, networking, sole tenancy to open the settings panel.

  4. On the Sole tenancy tab, click Browse to view the available node groups in the current project. The Sole-tenant node page appears, displaying a list of available node groups.

  5. On the Sole-tenant node page, select the applicable node group from the list and then click Select to return to the Sole tenancy tab. The node affinity labels field populates with the information you selected. This setting ensures that machine catalogs created from the instance will be deployed to the selected node group.

  6. Click Create to create the instance.

Set a node affinity label for an existing instance

To set the node affinity label:

  1. In the GCP console, click the terminal icon in the top-right corner to launch the Google Cloud Shell:

    Google Cloud console - terminal icon

    A terminal window appears at the bottom of the user interface. In the Google Cloud Shell terminal window, use the gcloud compute instances command to set a node affinity label. Include the following information in the gcloud command:

    • Name of the VM. For example, use an existing VM named s*2019-vda-base.*
    • Name of the node group. Use the node group name you previously created. For example, mh-sole-tenant-node-group-1.
    • The zone where the instance resides. For example, the VM resides in the *us-east-1b* zone.

    For example, type the following command in the terminal window:

    • gcloud compute instances set-scheduling "s2019-vda-base" --node-group="mh-sole-tenant-node-group-1" --zone="us-east1-b"

    For more information about the gcloud compute instances command, see the Google Developer Tools documentation at https://cloud.google.com/sdk/gcloud/reference/beta/compute/instances/set-scheduling.

  2. Navigate to the VM instance details page of the instance and verify that the Node Affinities field populates with the label.

Create a machine catalog

After setting the node affinity label, configure the machine catalog.

More information