Desktop and Application Streaming

Managing Amazon Linux 2 Amazon WorkSpaces with AWS OpsWorks for Puppet Enterprise

Amazon WorkSpaces is a managed, secure cloud desktop service. You can use Amazon WorkSpaces to provision either Windows or Linux desktops in just a few minutes and quickly scale to provide thousands of desktops to workers across the globe. With WorkSpaces, users can connect securely from anywhere using the software client or a supported web browser.

In June 2018, AWS announced that WorkSpaces are now available with Amazon Linux 2. This allows you to provide the same level of security and scalability to users who need Linux-based systems that you already provide for your Windows users. With Windows-based systems, you can use Active Directory Group Policy to control the streaming behavior and the accessibility of your WorkSpaces.

In this post, I demonstrate how to use OpsWorks for Puppet Enterprise to achieve the same level of control with Linux-based systems.


In Puppet, a module consists of a collection of resources, classes, files, definition, and templates. For this post, I created a sample Puppet module for configuration options you would expect for Linux WorkSpaces management. The module allows administrators to control access to their WorkSpaces and PCoIP settings. The source is available from


You need three Puppet modules for this procedure. Now that you have a sample Linux WorkSpaces module, you also need the stdlib and saz-sudo modules:

  • The stdlib module provides a standard library of resources for Puppet modules and can be found at .
  • The saz-sudo module allows administrators to configure sudo permissions with Puppet. It can be found on at .


To follow the steps in this post, you need the following:

  • An AWS environment with Amazon WorkSpaces configured
  • An Amazon Linux 2 WorkSpace to use as your Gold Image
  • AWS OpsWorks for Puppet Enterprise
  • WorkSpaces connectivity to your Puppet Enterprise servers
  • Internet connectivity from your Puppet Enterprise servers
  • System connectivity to your OpsWorks instance, along with the necessary management tools (for example, Git, the AWS CLI, Puppet tools)

Step 1: Modify your Puppetfile

To use the modules, add them to your local Puppetfile and push the change to your OpsWorks instance. For the modules on the Puppet Forge, specify the module name and desired version. Because the sample module is not on the Forge, specify the Git repo.

  1. Navigate to the local clone of your control repository.
  2. Open Puppetfile in your text editor of choice.
  3. Add the following after the existing mod statements:
    mod 'puppetlabs-stdlib', '5.1.0'
    mod 'saz-sudo', '5.0.0'
    mod 'amazon-linuxws',
        :git => ''
  4. Save the file.
  5. Push the change to your OpsWorks control repo, by running the following command:
    git add Puppetfile
    git commit -m “Added amazon-linuxws, saz-sudo and stdlib”
    git push origin production

Step 2: Deploy the changes to your Puppet Enterprise master

  1. Change to the root of your OpsWorks Starter Kit.
  2. Request an access token by running the following command:
    puppet-access login --config-file .config/puppetlabs/client-tools/puppet-access.conf --lifetime 8h
  3. Deploy the code changes by running the following command:
    puppet-code deploy --all --wait --config-file .config/puppet-code.conf 

Step 3. Configure your Puppet Enterprise master to allow agent installation without the AWS CLI

By default, OpsWorks enables administrators to install Puppet agents using the AWS CLI. This alleviates the need for administrators to approve certificates and instead uses IAM instance roles. As a managed service, WorkSpaces do not have IAM instance roles.

The following steps show how to pull down and install the agent automatically. The procedure requires that you re-enable the traditional, certificate-based, method. To do this:

  1. Log in to the Puppet Enterprise console.
  2. Under CONFIGURE, choose Classification.
  3. Under PE infrastructure, choose PE master.
  4. On the Configuration tab, look for class puppet_enterprise::profile::master. Under Parameters, add a parameter with the parameter name allow_unauthenticated_ca and value set to true.
  5. Commit the change.

Step 4. Set up a collection for your Linux WorkSpace in the Puppet Enterprise console

Puppet uses criteria -based collections to target and apply policies to your systems. To use Puppet to manage your Amazon Linux 2 WorkSpaces, create a collection for them. The policy that you define should only apply to those instances. To do this:

  1. Log in to the Puppet Enterprise console.
  2. Under CONFIGURE, choose Classification, Add group….
  3. Specify values for Parent name, Group name, and Environment, and then choose Add, as shown in the following screenshot. 
  4. Browse to the group that you just created.
  5. On the Rules tab, choose Nodes must match all rules, and specify the rules to identify the WorkSpaces that this collection must contain, as shown in the following screenshot.
  6. Commit the changes.

Note: In my test environment, I deploy WorkSpaces in subnets based on their use case. So, I use operating system, kernel, and IP address to identify the WorkSpaces that this collection should contain. Because my WorkSpaces are in either or, I use a regular expression to match addresses in that range. Then, to ensure that I only target Linux WorkSpaces, I specified that the OS must be Amazon and the kernel must be Linux. By restricting the target, I make sure not to apply the policy in unwanted ways—for example, to the Windows WorkSpaces that I manage with OpsWorks. Finally, I note an exception to the collection. This exception is designed to ensure the test system at and is not affected by any configurations I apply.

Step 5: Configure the collection settings

Now that you have defined your collection, specify the policies to apply to that collection. In this case, use the linuxws class in your sample module.

  1. On the Configuration tab, in the Add new class field, select linuxws, and then choose Add class.
  2. Under the newly added linuxws class, set the desired parameters, as shown in the following screenshot. Choose Add parameter after each addition.

wsloglevel – This can be set from 0 to 3 and dictates the log verbosity, with 0 being no logs and 3 being the most verbose. Set this parameter in Options. Parameter defaults to 1 if unset.

clipboard – This dictates the clipboard-sharing behavior. It is optional and defaults to 0 (Disabled in both directions) if left unset. The options are:

0 – Disabled in both directions

1 – Enabled in both directions

2 – Enabled client to agent only

3 – Enabled agent to client only

domainname – This is the short name for the Active Directory Domain where your users are located.

userlist – This is an array of users and groups you want to have sudo and ssh access to the system. The format is [“user1”,”group1”].

3. Choose Commit 4 changes.

Step 6: Create a new image to automatically connect to OpsWorks

  1. Connect to your golden image WorkSpace and open a terminal window.
  2. To automatically run the install script, modify the rc.local file by running the following command:
    $ sudo vi /etc/rc.d/rc.local
  3. Make rc.local executable by running the following command:
    $ chmod +x /etc/rc.d/rc.local
  4. Add the line /bin/ & and press Esc.
  5. Type :wq and press Enter.
  6. Create the deployment script by running the following command:
    $ sudo vi /bin/
  7. Enter the following code in the script:
    # Wait 5 minutes before triggering the install
    sleep 600
    #Download and install agent from OpsWorks Server
    curl -k https://<INSERT THE URL OF YOUR PM HERE>/packages/current/install.bash | bash
    #Remove cron job after 1 run
    sed -i '/\/bin\/' /etc/rc.d/rc.local
    #reset permissions on /etc/rc.d/rc.local
    chmod -x /etc/rc.d/rc.local
    # Remove file after 1 run
    rm $0
  8. Make executable by running the following command:
    $ chmod +x /bin/
  9. Disconnect from your reference WorkSpace and return to the WorkSpaces console by browsing to
  10. In the left navigation pane, select WorkSpaces.
  11. Check the box next to your reference system, and choose Actions.
  12. Choose Create Image, and provide an image name and description.
  13. Choose Create Image. This step takes several minutes.

Step 7: Create and deploy your new bundle

After your image has completed capturing, create a bundle:

  1. In the left navigation pane, choose Images.
  2. Check the box corresponding to your new image.
  3. Choose Actions, Create Bundle.
  4. Provide an image name and description, and set the bundle defaults.
  5. Choose Create Bundle.

Using this bundle, deploy WorkSpaces:

  1. In the left navigation pane, choose WorkSpaces, Launch WorkSpaces.
  2. Select a directory. Make sure that the WorkSpaces in the corresponding subnets and security group can access your OpsWorks server.
  3. Use Search to find the users to add, select the target users, and then choose Add Selected.
  4. Choose Next Step.
  5. Select your new bundle, and choose Next Step.
  6. Make any desired changes to the Running Mode and Encryption settings, and choose Next Step.
  7. Verify your settings, and choose Launch WorkSpaces.

Step 8: Approve access to your Puppet master in the Puppet Enterprise console

To ensure that only approved systems can communicate with your Puppet master, Puppet uses certificate approvals. Each time that Puppet presents a new system for certification, you can choose to approve or deny the connection.

  1. Browse to your Puppet Enterprise console, and log in.
  2. From the left menu, under SETUP, choose Unsigned certs.
  3. If all the certificates correspond to systems to add, choose Approve All, otherwise, approve only the ones you want.


In this post, I showed you how you can use AWS OpsWorks for Puppet Enterprise to manage Amazon Linux 2 WorkSpaces at scale. Using this approach gives Linux WorkSpace administrators the same level of control they are used to with their Windows WorkSpaces.