PAWS Documentation. Release Eduardo Cerqueira

Transcription

1 PAWS Documentation Release Eduardo Cerqueira Jul 09, 2018

2

3 Contents 1 Benefits 3 2 Usage 5 3 Layers 7 4 Finally Installation Support Matrix Prerequisites Application Container Finally Getting Started Prerequisites How To Run Providers Openstack Libvirt Files ansible.cfg credentials.yaml resources.yaml resources.paws powershell files group files Tasks Provision Teardown Configure Group Show Groups What is a group? What is the structure of a group? Example of a group Example of a group with multiple resources i

4 ii How you can create your own group? PowerShell Why PowerShell? PAWS and PowerShell [ws] References Contributing Setup your local environment Build New release IDE FAQ How can I see more logging messages? Are there other ways to use Openstack credentials? Can I use PAWS just to give me a Windows and how can I access it? What Windows images are available in my Openstack provider? Why do I get an exception after removing paws and reinstalling paws? How can I reboot my Windows system? Where can I find more PowerShell scripts? Is there any difference between Windows to run in Openstack and DVD media installation for Windows? Why Administrator account comes with no password? Why I can t use a small flavor to provision a Windows? Links Contact Authors IRC Mailing List Report Issue

5 A linux based tool focused on simplifying the process to provision Windows systems and configure Windows services. To easily test hybrid environments (Linux & Windows). Contents 1

6 2 Contents

7 CHAPTER 1 Benefits 1. Build and destroy Windows environments within minutes. 2. Use of Windows during trial evaluation period. 3. Fresh environment to validate bugs. 4. Reduce time required to maintain golden environments. 5. Configure Windows using native PowerShell language. 6. Share scripts to build Windows environments to eliminate need to create scripts that may already exist. 3

8 4 Chapter 1. Benefits

9 CHAPTER 2 Usage Developers working on components that interact with Windows platforms can benefit by paws to create a test environment to verify their code changes. Quality Engineers needing to test products within hybrid environments can benefit by paws to create their fully configured test environment. Allowing them to easily begin test execution. DevOps can use paws to preview changes to production hybrid environments to ensure changes are stable before making final deployment. 5

10 6 Chapter 2. Usage

11 CHAPTER 3 Layers Paws is composed of three layers as shown below: PAWS Client: Paws command line client (Linux based). Providers: Infrastructure hosting the Windows systems. See providers to view the current available providers. Ansible cloud modules currently are used to handle provisioning in available infrastructures. WS: Centralized repository where all PowerShell scripts reside. Users can use the PowerShells in the repo or they can define a set of PowerShells from another repo or local folder. This is all configurable. 7

12 8 Chapter 3. Layers

13 CHAPTER 4 Finally.. Paws is NOT another tool to provision Windows systems and does not intend replace any existing configuration management tool. Paws is a great choice to be used for easily spinning up Windows systems and performing a remote desktop connection or to be used in CI/CD environment. We envision paws as the solution to efficiently spin up and configure free Windows systems leaving hybrid environments no longer an issue for development or testing purposes. 4.1 Installation Support Matrix Operating System Version Application Container CentOS OS >= 7.2 Yes Yes Fedora Supported Releases Yes Yes Red Hat Enterprise Linux OS >= 7.2 Yes No Prerequisites To install paws via pip, you will need to install the following system dependencies in order to have the install succeed. 1 # dnf package manager 2 sudo dnf install -y git gcc make python-devel python-setuptools \ 3 python-pip openssl openssl-devel libffi-devel redhat-rpm-config \ 4 libvirt libvirt-devel virt-install 5 6 # yum package manager 7 sudo yum install -y git gcc make python-devel python-setuptools \ (continues on next page) 9

14 8 python-pip openssl openssl-devel libffi-devel redhat-rpm-config \ 9 libvirt libvirt-devel virt-install (continued from previous page) Application PIP 1 pip install paws-cli RPM CentOS 1 # install epel repo for package dependencies 2 sudo yum install -y noarch.rpm 3 4 # install paws repo 5 sudo curl -o /etc/yum.repos.d/paws.repo 6 /coprs/eduardocerqueira/paws/repo/epel-7/eduardocerqueira-paws-epel-7.repo 7 8 # install paws 9 sudo yum install -y paws Fedora 1 # install paws repo 2 sudo curl -o /etc/yum.repos.d/paws.repo 3 /coprs/eduardocerqueira/paws/repo/fedora-<version>/eduardocerqueira-paws-\ 4 fedora-<version>.repo 5 6 # install paws 7 sudo dnf install -y paws OR 1 # install dnf plugins core 2 sudo dnf install dnf-plugins-core -y 3 4 # enable paws copr repo 5 sudo dnf copr enable eduardocerqueira/paws -y 6 7 # install paws 8 sudo dnf install -y paws Red Hat Enterprise Linux 1 # register system 2 sudo subscription-manager register (continues on next page) 10 Chapter 4. Finally..

15 3 4 # attach and enable repos 5 sudo subscription-manager attach 6 sudo subscription-manager repos --enable rhel-7-<variant>-rpms 7 (continued from previous page) 8 # enable epel repo for package dependencies (optional) 9 sudo yum install -y noarch.rpm # install paws repo 12 sudo curl -o /etc/yum.repos.d/paws.repo 13 coprs/eduardocerqueira/paws/repo/epel-7/eduardocerqueira-paws-epel-7.repo # install paws 16 sudo yum install -y paws Warning: RPM installation will perform a post install task to install extra Python packages using pip. This is required because at this current point some required packages not available via RPM. You can view packages installed here: Pywinrm: required for remote Windows management Container 1 # pull docker image 2 sudo docker pull rywillia/paws:latest 3 4 # clone ws repo 5 cd ~ && git clone ws 6 7 # run docker and mount a new volume to the local ws repo folder 8 sudo docker run -it --name paws -v /home/user/ws/:/home/paws/ws rywillia/paws:latest bash Finally.. By default PAWS searches for /home/user/ws as folder for userdir where scripts should be saved. See userdir 4.2 Getting Started Prerequisites Clone a local copy of the ws repository. This will provide you with paws files for getting started. 1 cd ~ && git clone Getting Started 11

16 Important: We recommend storing the ws repo within your users home directory. By default paws will look for a ws directory at /home/$user/ws to load files. You can always override this by defining -ud option at runtime. We strongly recommend that you read about paws files How To Run To run paws, just issue the following command in a terminal. 1 paws You can view more about each paws task by providing the help option. 1 paws <task> --help Provision Provision task will provision Windows systems in their given provider defined. You can find more details about configuring your providers credentials at the following: provider credentials. You will want to modify the resources.yaml file within your local copy of ws repository stored within your user directory folder path. resources: - name: windows provider: openstack count: 1 image: win-2016-serverstandard-x86_64-released flavor: m1.xlarge network: keypair: keypair ssh_private_key: /home/user/.ssh/id_rsa administrator_password: my_password@2018 You can find more details about configuring your resources file at the following: resources.yaml. Once your files are set, go ahead and call paws provision task. provisioned and ready for use! 1 paws provision Shortly you should have your Windows system Note: More details about provision task can be found at the following: provision task. Teardown Teardown task will teardown Windows systems in their given provider defined. It requires both files (credentials.yaml & resources.yaml) which were used in provision task. These files define provider credentials and which systems to delete. Once your files are set, go ahead and call paws teardown task. Shortly you should see your Windows systems deleted. 12 Chapter 4. Finally..

17 1 paws teardown Note: More details about teardown task can be found at the following: teardown task. Configure Configure task will configure Windows services on Windows systems by either running Ansible Playbooks or Windows PowerShell scripts. At top of this page you saw how to clone ws repository repo that contains some samples of powershell and scripts you can use here. Example powershell scripts can be found at the following: /home/$user/ws/powershell. Example ansible playbooks can be found at the following: /home/$user/ws/ansible. Below is an example calling a powershell script to list system information for the defined resources within resources.yaml. 1 paws configure powershell/get_system_info.ps1 Here is an example calling an ansible playbook to install packages on the defined resources within resources.yaml. 1 paws configure ansible/install_packages.yml Note: More details about configure task can be found at the following: configure task. Group Group task will run multiple paws commands as one command. A group is a YAML file which defines a list of paws tasks to run. Example group files can be found at the following: /home/$user/ws/group. Below is an example calling a paws group file to configure a 2012 Windows Active Directory server. 1 paws group -n group/2012_winad.yaml Note: More details about group task can be found at the following: group task. Show Show task will display system resources based on what is defined within your resources.yaml file. Show is helpful when you may have forgotten the password for a defined Windows resource. Below is an example calling paws show to view system resources/details. 1 paws show 4.2. Getting Started 13

18 Note: More details about show task can be found at the following: show task. 4.3 Providers The definition of provider for PAWS is the location where the Windows will be provisioned and managed by PAWS. it is the list of providers supported: Openstack provider Libvirt provider Openstack PAWS is integrated with Openstack and able to provision, configure and manage Windows virtual machines running on public or private clouds. Path: /home/$user/ws/credentials.yaml credentials: - provider: openstack os_auth_url: os_username: <username> os_password: <password> os_project_name: <project_name> os_region: <region> Field name Description Value provider name of provider where your Windows system will openstack, libvirt live os_auth_url OpenStack URL/port for authentication HTTP URL see in file above to use OSP7 os_username Username to login to OpenStack tenant tenant username os_password Password to login to OpenStack tenant tenant password os_project_name Name of the OpenStack tenant or project tenant or project Path: /home/$user/ws/resources.yaml resources: - name: windows_server_01 provider: openstack count: 1 image: win-2016-serverstandard-x86_64-released flavor: m1.xlarge network: keypair: <keypair> ssh_private_key: /home/$user/.ssh/<private_key> administrator_password: my_password@2018 provision_attempts: Chapter 4. Finally..

19 PS: resources accepts multiple resources definition. Field name name Description The name that will be given when the instance is provisioned (Openstack sets this as the instance name). When count > 1 during provisioning the instance name will be automatically appended with sequential numbers. provider provider name to use Yes count The number of identical resources to create. This count only applies to each specific resource Yes section. It does not apply to all resources in the file. image The name of the image to be used to create the instance. The Windows image should exist and your provider account must have permission to use it. Check Openstack in FAQ to see how you can get the full list of current Windows images in your Openstack provider Yes flavor network The flavor name or ID which should be used when creating the new instance Check Openstack FAQ to see how you can get the full list of current Windows flavors in your Openstack provider The name or ID of a network to attach this instance to. This network will provide the floating IP to your instance. You will want to supply the external network name as your network if it has a router connecting it to an internal network. Required Yes keypair The key pair name to be used when creating an instance Yes ssh_private_key Absolute path from your host machine to the SSH private key to login to system via SSH Yes administrator_password The administrator password to set on the Windows system after provisioning has finished. No provision_attempts The number of attempts to wait for the provision request to finish building. Default is 30. snapshot Take a snapshot for a given resource. Yes Yes No No Note: -snapshot: Take a snapshot for a given resource. # example 1: create snapshot and clean previous snapshots for the vm resources: - name: MY_WINDOWS_VM snapshot: create: True clean: True # example 2: do not create snapshot and only clean previous snapshots for the vm: resources: - name: MY_WINDOWS_VM snapshot: create: False clean: True # example 3: create snapshot, override default settings for attempts and # delay between attempts when checking if snapshot was created # default attempts is 30 and default delay is 20 seconds resources: - name: MY_WINDOWS_VM snapshot: create: True attempts: 60 delay: Providers 15

20 single network An Openstack tenant which has a single network connected to a public network. You can find your Openstacks network topology by accessing the following link with your credentials http: //<hostname>/dashboard/project/network_topology/ Example resources.yaml: resources: - name: windows_server_01 provider: openstack count: 1 image: win-2016-serverstandard-x86_64-released flavor: m1.xlarge network: /22 keypair: <keypair> ssh_private_key: /home/$user/.ssh/<private_key> administrator_password: my_password@ Chapter 4. Finally..

21 Note: Looking at the network topology image above. You will see a router is connected to the /22 external network. This external network can be used as the network name in your resources.yaml. multiple networks A Openstack tenant which has multiple networks connected to a public network. You can find your Openstacks network topology by accessing the following link with your credentials http: //<hostname>/dashboard/project/network_topology/ Example resources.yaml: resources: - name: windows_server_01 provider: openstack count: 1 image: win-2016-serverstandard-x86_64-released flavor: m1.xlarge network: <network_name> floating_ip_pools: /22 (continues on next page) 4.3. Providers 17

22 network: /22 keypair: <keypair> ssh_private_key: /home/$user/.ssh/<private_key> administrator_password: (continued from previous page) In this example we want to highlight on two keys that will need to be set correctly if your Openstack tenant has multiple networks connected to the same public network. For information about all other keys, please reference to the descriptions above. Note: (REQUIRED) - network: The network name should define which internal network you want the instance to be created on. It should not be the name of the external network to attach too. E.g. Looking at the network topology image above, we will want to give the name of one of the internal networks to use. In this case we will give idm-ad-domain. - floating_ip_pools: The name of the external network to use to create the floating IP for the provisioned instance. E.g. Looking at the network topology image above, we will want to give the floating_ip_pools a value of /22. Since this is the external network connected to one of the internal networks in the image. Attention: If your Openstack has multiple networks connected to the same external network, it is REQUIRED that you set the floating_ippools key. This key tells paws which external network to use to create the floating IP. Setting both network and floating_ip_pools for a single network connected to an external network will work as well Libvirt PAWS is integrated with Libvirt and able to provision, configure and manage Windows virtual machines running locally. PAWS Image Service is an internal repository for Windows QCOW images. If you have your own QCOW Windows images ready to run on Libvirt you only need to configure your paws files. To run PAWS with libvirt you need to create credentials.yaml and resources.yaml see below details for these two files and a sample. To configure your machine to run PAWS with libvirt follow the section Running Windows on VM path: /home/$user/ws/credentials.yaml credentials: - provider: libvirt qemu_instance: qemu:///system imgsrv_url: 18 Chapter 4. Finally..

23 Field Description name provider name of provider where your Windows system will live qemu_instance specify the instance for QEMU driver to use imgsrv_url URL to retrieve the pre-configured Windows image for Libvirt Value openstack, libvirt system, session for more information drvqemu.html or for dev purpose, if running IMGSRV locally you can use path: /home/$user/ws/resources.yaml resources: - name: windows_server_01 provider: libvirt memory: 4000 vcpu: 1 disk_source: /home/$user/downloads/<windows_qcow> win_username: Administrator win_password: my_password@2018 Field name Description Required name The name that will be given when the instance is provisioned Yes provider provider name to use Yes memory The amount of memory you want to set for the new virtual machine that will be provisioned Yes must be in MB vcpu The number of virtual CPU you want to allocate for the new virtual machine Yes disk_source The location in your local machine where the pre-configured Windows image will be saved. Yes This file is the storage drive for your virtual machine win_username the username pre-configured in the Windows image. You get this from IMGSRV Yes win_password the password pre-configured in the Windows image. You get this from IMGSRV Yes 4.4 Files This document will explain in more detail about files used by paws ansible.cfg Paws creates an Ansible configuration file stored at the default user directory /home/$user/paws to be used when run. This file will not have Ansible generate playbook.retry files. Since this file lives in the user directory, you can modify Ansible settings if you wish. Please be aware if you change settings not supported by paws, you could see potential failures. See Ansible doc for more information about.retry at retry-files-enabled 4.4. Files 19

24 4.4.2 credentials.yaml Dictionary of your providers credentials. Hint: For Openstack as provider, you can use Openstack system environment variables instead of the credentials.yaml file. The physical credentials.yaml file is the primary source. If you are using system environments but still have credentials.yaml in your paws user directory, paws will use the file. For Openstack provider you can use Openstack system environment variables Check Openstack FAQ to see where to get and how to use Openstack system environment variables openstack.org/keystone/latest/install/keystone-openrc.html Example credentials.yaml: credentials - provider: openstack os_auth_url: os_username: username os_password: password os_project_name: tenant Note: see Openstack provider for fields definition see Libvirt provider for fields definition resources.yaml A list of resources that you would like to provision. Example resources.yaml for Openstack provider: resources: - name: MY_WINDOWS_VM count: 1 image: win-2012-r2 flavor: 4 network: network_name keypair: my_key_pair ssh_private_key: /home/user/.ssh/id_rsa administrator_password: my_password@2016 provision_attempts: 30 Note: see Openstack provider for fields definition see Libvirt provider for fields definition 20 Chapter 4. Finally..

25 4.4.4 resources.paws A list of resources that have been provisioned by provision task. This file will be generated when provision task is finished. It is stored under the users directory. Example resources.paws: resources: - name: windows_2012_server public_v4: private_v4: ssh_key_file: /home/user/.ssh/id_rsa keypair: my_key_pair id: 79f0dd24-28f0-45e1-b560-a299767fa969 win_password: my_password@2016 win_username: Administrator Note: - name: The name of the instance created in Openstack. - public_v4: The public IPv4 address. - private_v4: The private (internal) IPv4 address. - ssh_key_file: The SSH private key to login to the system via SSH. - keypair: They key pair associated with the instance when created. - id: The ID of the instance running in Openstack. - win_password: The password to login to your instance. This can be used by SSH or RDP (Remote Desktop Protocol). - win_username: The username to login to your instance. This can be used by SSH or RDP (Remote Desktop Protocol) powershell files For more information about PowerShell scripts can be found here: PowerShell group files For more information about groups can be found here: group. Tip: Files under powershell or group directories can be modified by your need. These are just base templates to help get you started with paws Files 21

26 4.5 Tasks This document will go into more detail about each paws task. Global options available to all paws commands. Argument Default Required Description -ud, userdir /home/$user/ws Yes User directory where paws files reside -v, verbose No Enables verbose logging -h, help No Enable to show help menu Provision DESCRIPTION Provision task will provision system resources in your provider that you have defined inside resources.yaml. If something unexpected happens during provisioning. Paws will invoke the teardown task automatically. ARGUMENTS Argument Default Required Description -c, credentials credentials.yaml Yes Providers credentials settings -t, topology resources.yaml Yes System resources definition -h, help No Enable to show help menu EXAMPLES 1 # provision using default options 2 paws provision 3 4 # provision using default options with verbose logging 5 paws -v provision 6 7 # provision overriding user directory 8 paws provision -ud /tmp/ws 9 10 # show help menu 11 paws provision --help Note: One completion, you will find a new file resources.paws stored within your user directory. This file contains updated information for the system resource provisioned. resources: - name: windows_server_01 public_v4: private_v4: ssh_key_file: /home/$user/.ssh/id_rsa keypair: my_key_pair id: 79f0dd24-28f0-45e1-b560-a299767fa969 win_password: my_password@2018 win_username: Administrator 22 Chapter 4. Finally..

27 4.5.2 Teardown DESCRIPTION Teardown task will teardown system resources in your supplied provider. It will teardown the resources you have defined inside your resources.yaml if they are active instances. ARGUMENTS Argument Default Required Description -c, credentials credentials.yaml Yes Providers credentials settings -t, topology resources.yaml Yes System resources definition -h, help No Enable to show help menu EXAMPLES 1 # teardown using default options 2 paws teardown 3 4 # teardown using default options with verbose logging 5 paws -v teardown 6 7 # teardown overriding user directory 8 paws -ud /tmp/ws teardown 9 10 # show help menu 11 paws teardown --help Configure DESCRIPTION Configure task will perform configuration on Windows systems by running either an Ansible playbook or Windows PowerShell scripts. ARGUMENTS Argument Default Required Description [SCRIPT] Yes Playbook or PowerShell script to execute -t, topology resources.yaml Yes System resources definition -sv, script_vars No Playbook or PowerShell script variables -s, system All system resources No Systems to configure -h, help No Enable to show help menu EXAMPLES 1 # configure via ansible playbook with no input variables 2 paws configure ansible/task01.yml 3 4 # configure via ansible playbook with input variables (format=file) 5 paws configure ansible/task01.yml -sv ansible/my_vars.json 6 7 # configure via ansible playbook with input variables (format=string) 8 paws configure ansible/task01.yml -sv "{'key01': ['value01', 'value02']}" (continues on next page) 4.5. Tasks 23

28 9 10 # configure via windows powershell script with no input variables 11 paws configure powershell/task01.ps # configure via windows powershell script with input varaibles (format=file) 14 paws configure powershell/task01.ps1 -sv powershell/my_vars.json 15 (continued from previous page) 16 # configure via windows powershell script with input variables (format=string) 17 paws configure powershell/task01.ps1 -sv "-command upgrade Group DESCRIPTION Group task gives users the ability to bulk multiple paws task calls into a single paws call. ARGUMENTS Argument Default Required Description -ud, userdir /home/$user/ws YES User directory -n, name Yes Group template filename -h, help No Enable to show help menu EXAMPLES # group using default options and setting group file paws group -n group/my_group.yaml # group overriding user directory paws -ud /tmp/ws group -n group/my_group.yaml # show help menu paws group --help Note: To learn how to create a paws group file, visit the following: Create group file Show DESCRIPTION Show task will display system resources in your supplied provider. It assumes the provision task was called previously and your system resource was successfully provisioned. If show does not find any system resources in your supplied provider. A warning message will be displayed instead. ARGUMENTS Argument Default Required Description -c, credentials credentials.yaml Yes Providers credentials settings -t, topology resources.yaml Yes System resources definition -h, help No Enable to show help menu 24 Chapter 4. Finally..

29 EXAMPLES 1 # show windows systems using default options 2 paws show 3 4 # show using default options with verbose logging 5 paws -v show 6 7 # show overriding user directory 8 paws -ud /tmp/ws show 9 10 # show help menu 11 paws show --help 4.6 Groups This document will explain what a group is, the file structure of a group and how you can create your own group What is a group? A group is an easy way to bulk multiple single paws calls into one call What is the structure of a group? A group file is a YAML formatted file which contains three sections: Header, Vars and Tasks. Before starting group execution PAWS performs a data validation in a group yaml file. The first part of validation is to check file schema that must contains all basic elements header, vars and tasks. The second part is to check data declared. At this current version PAWS runs regular expression match as showed below: # regular expressions to validate content of group yaml file GROUP_REQUIRED = { 'header': [ {'name': '.*.'}, {'description': '.*.'}, {'maintainer': "[a-za-z0-9_.+-]+@[a-za-z0-9-]+\.[a-za-z0-9-.]+"}], 'vars': [{'topology': '(.*.yaml)$ (.*.yml)$'}]} Header The header section contains general information about the group. This information isn t used directly when calling paws but is helpful when someone wants to use your group within their testing environment. The header section is in format of a dictionary. You will need to declare the following keys: name: Name of the group. Required: True Type: String Validation: Must contains at least one string. Multi-line is allowed 4.6. Groups 25

30 description: A short description what the group is doing. Required: True Type: String Validation: Must contains at least one string. Multi-line is allowed maintainer: The address for the maintainer of the group. Required: True Type: String Validation: address format Here is an example of a header section: group: - header: name: Windows server 2012 Active Directory group description: Provision and configure Windows vm for AD maintainer: rwilliams5262@gmail.com Vars The vars section contains common options used throughout all tasks you want to run. credentials: which defines the credentials filename. Required: False Type: String Validation: As optional field it doesn t have any validation. Notes: For Openstack provider you can use environmet system variable as credentials so you can skip credentials attribute in your group file. The same won t work if you want to use Libvirt as provider. topology: which defines the topology file to be used. This is the file which contains your systems you would like to provision or are already provisioned. Required: True Type: String Validation: any file must ends with.yaml or.yml These keys can come from any of the options a task has available. Mostly you will see options such as (user directory, credentails, topology) defined here. All others will be defined by each specific task. Example of a vars section: group: - vars: credentials: credentials.yaml topology: resources.yaml 26 Chapter 4. Finally..

31 Tasks The tasks section is the main part to a group. This is where you will define all the tasks you want to run. The order that you define your tasks is the order that paws will execute them. Each task is in the format of a dictionary. You will need to declare the following keys: name: Name of the task. Required: True Type: String Validation: none task: Name of the paws task to call. Required: True Type: String Validation: None args: Options that you would like to pass to that task. Required: False Type: dict Validation: None Here is an example of a tasks section: group: - tasks: - name: Provision Windows task: provision - name: Get Windows system information task: configure args: - script: powershell/get_system_info.ps1 - name: Reboot Windows task: configure args: - script: powershell/reboot.ps1 As you can see we have declared three tasks to run: 1. First it will run the provision task to create a Windows system based on the system defined in the topology file set in the vars section. 2. Second it will run the configure task. It will execute the script that was specified. 3. Third it will run the configure task again. This will run the reboot.ps1 PowerShell script to reboot the system Groups 27

32 4.6.3 Example of a group group: - header: name: Display Windows system information description: Provision Windows system and display system information maintainer: rwilliams5262@gmail.com - vars: credentials: credentials.yaml topology: resources.yaml - tasks: - name: Provision Windows task: provision - name: Get Windows system information task: configure args: - script: powershell/get_system_info.ps1 - name: Reboot Windows task: configure args: - script: powershell/reboot.ps1 Paws version supports multiple resources. This means that you can define multiple resources inside your resources.yaml and then configure them. By default configure task will run PowerShell scripts on all resources defined inside resources.yaml. If you want to set only a certain system to run the PowerShell against you can pass the system argument. This goes the same for groups. The system name you give must match the one inside your resources.yaml. Below is an example of running a task only on a certain system Example of a group with multiple resources group: - header: name: Display Windows system information description: Provision Windows system and display system information maintainer: rwilliams5262@gmail.com - vars: credentials: credentials.yaml topology: resources.yaml - tasks: - name: Provision Windows task: provision - name: Get Windows system information task: configure args: - script: powershell/get_system_info.ps1 - system: - windows2012 (continues on next page) 28 Chapter 4. Finally..

33 - name: Reboot Windows task: configure args: - script: powershell/reboot.ps1 (continued from previous page) How you can create your own group? Now that you understand the three sections to a group and what they offer. You can easily begin creating your own groups! Please feel free to use the default group templates as a starting point and expand from there! Attention: One thing to note is if your group contains a number of configure tasks. You will need to keep all the PowerShell scripts and necessary variable files stored within your user directory where your group file is located. If you want to share your group file with someone else to use, you will need to provide them with all files: group, PowerShells, etc. When installing Windows features, some might require a reboot in order to take effect. If you issue the reboot PowerShell script and go to run another PowerShell script right after. It might fail because the system is going to go down. In order to handle these paws group offers a feature called wait. Wait is very simple: it will wait a duration that you specify. Lets look at the following example: - tasks: - name: Windows preparation task: configure args: - script: powershell/2012_ad_preparation.ps1 - script_vars: powershell/my_vars.json - name: Reboot Windows task: configure args: - script: powershell/reboot.ps1 - name: Wait for Windows to come back online task: wait duration: 30 - name: Windows setup step 1 task: configure args: - script: powershell/ad_setup_step1.ps1 - script_vars: powershell/my_vars.json As you can see the wait is given after the reboot and will wait 30 seconds before running the next task in the list. This allows users to easily customize their workflow Groups 29

34 4.7 PowerShell PowerShell (including Windows PowerShell and PowerShell Core) 1 is a task automation and configuration management framework from Microsoft, consisting of a command-line shell and associated scripting language built on the.net Framework Why PowerShell? PowerShell is the native script language for Microsoft Operating Systems. PowerShell gives us access to a large number of MS libraries, making scripts easy to interact with MS components and features. PowerShell can interact with a dizzying number of technologies. PowerShell is object-based. PowerShell can help anyone working in the Microsoft ecosystem. 2 Windows PowerShell is a shell developed by Microsoft for purposes of task automation and configuration management. This powerful shell is based on the.net framework and it includes a command-line shell and a scripting language. On top of the standard command-line shell, you can also find the Windows PowerShell ISE PAWS and PowerShell [ws] PAWS uses PowerShell scripts to install, configure and perform any change in a Windows previously provisioned. WS Windows Scripts is a git repo to store PowerShell scripts to be used during PAWS execution. Everybody can use this repository and the idea is to use this a centralized place that people can re-use scripts already developed and contribute to expand for others use cases. WS REPO URL: We strongly recommend cloning this repository to your user directory /home/$user/paws powershell: We currently have some PowerShell scripts that you can start using with paws and more can be found here 3. group: A group may have one or more PowerShell script calls. Groups allow you to build and share your Windows pipeline. You can see more about groups at group task. Users can use all these scripts provided to run configure or group tasks. Users can pull or push their scripts/groups to this repository References 4.8 Contributing There are several ways to contribute with PAWS project and everyone is welcome: are you python or ansible guy? you can fix bugs or improve the application with new features Chapter 4. Finally..

35 are you Windows guy? you can add new powershell scripts at ws repo do you like writing? you can help on documentation. and too many others... testing, reporting issues and new ideas to be implemented by developer team Setup your local environment Before you dive into contributing to paws. You will need to setup your environment so you are able to test your code changes before submitting a code review. First enable the repositories on your system that paws requires. You can find these at the installation page. Next you will need to install packages needed for development. Most of these packages are dependencies that paws would install when installing by repository. From a terminal, run the following command based on your operating system. # Yum package manager sudo yum install -y git gcc make rpm-build\ python-devel python-setuptools python-pip python2-flake8 pylint\ python-kitchen openssl-devel libffi-devel\ python-oslo-serialization python-pep8 ansible krb5-workstation # Dnf package manager sudo dnf install -y git gcc make rpm-build\ python-devel python-setuptools python-pip python2-flake8 pylint\ python-kitchen openssl-devel libffi-devel\ python-oslo-serialization python-pep8 ansible krb5-workstation Once the development packages have been installed, go ahead and clone the paws and ws git repos. From a terminal, run the following command. git clone git@github.com:rhpit/paws.git git clone git@github.com:rhpit/ws.git We recommend you running in a Python virtual environment so from your terminal run the following commands. Create a python virtual environment, activate it and install required libs: # Switch directories to where you cloned paws git $ cd paws virtualenv -p /usr/bin/python2.7 venv_paws source venv_paws/bin/activate pip install -r test-requirements.txt --upgrade pip install -e Build Now that your environment is setup to build paws, lets go through the basics on building/installing paws from source. At the root of paws git folder there is a Makefile. From your terminal run the following command to see available options by paws. $ make 4.8. Contributing 31

36 Here are some of the common ones used by paws developers/contributors. Documentation From your terminal run the following command to build paws sphinx documentation. $ make doc A separated paws-doc folder will be created at same root as paws folder and you can open the full documentation locally in html format at file:///home/user/git/paws-doc/html/index.html Build RPM From your terminal run the following command to build paws RPM. $ make rpm From the console output you will see something similar as below stating where the RPM was generated. From there you can go ahead and install it. # Yum package manager Wrote: /home/cloud-user/paws/rpmbuild/rpms/noarch/paws noarch.rpm sudo yum install -y /home/cloud-user/paws/rpmbuild/rpms/noarch/paws noarch.rpm # Dnf package manager Wrote: /home/fedora/paws/rpmbuild/rpms/noarch/paws noarch.rpm sudo dnf install -y /home/fedora/paws/rpmbuild/rpms/noarch/paws noarch.rpm pip For development we recommend installing PAWS by pip as the main reason you can isolate the application running into a python virtual environment like example: virtualenv -p /usr/bin/python2.7 venv source venv/bin/activate (venv) pip install /home/user/git/paws/dist/paws tar.gz The install command above is using the local tar.gz built previously by running make pip command. It also could be installed from a pypi-test repo running: pip install --index-url paws Code check Before any commit make sure your code changes are following the code standard of this project running the command: cd paws make codecheck New release List of actions that need to be performed for a new release: 1. update paws/version.txt 2. update version and release variables in Makefile and paws.spec 3. make codecheck fix if needed 4. commit your changes 32 Chapter 4. Finally..

37 5. make doc ( access locally and double check before update upstream doc ) 6. make copr-dev 7. make copr-upstream IDE Eclipse pydev on eclipse and pydev fixing unresolved imports or to link source code to correct path double check: venv_paws in Python interpreter and project root folder as external libraries clean all / build projects see screenshots: 4.8. Contributing 33

38 If you are seeing the error module (setup) is missing interpreter line when running PAWS from your Eclipse IDE maybe for debug purpose you need to change the path for Working directory to anything else out of your source code. 4.9 FAQ This page contains common questions that may help you when using paws. Please check this page first to see if your question exists. If you are still unable to find a solution to your question, please send an to the members on the contact page. How can I see more logging messages? Are there other ways to use Openstack credentials? Can I use PAWS just to give me a Windows and how can I access it? What Windows images are available in my Openstack provider? Why do I get an exception after removing paws and reinstalling paws? How can I reboot my Windows system? Where can I find more PowerShell scripts? Is there any difference between Windows to run in Openstack and DVD media installation for Windows? Why Administrator account comes with no password? Why I can t use a small flavor to provision a Windows? 34 Chapter 4. Finally..

39 4.9.1 How can I see more logging messages? Add the -v argument to any paws task to view more logging messages. # Replace task with one of the available tasks paws <task> -v Are there other ways to use Openstack credentials? When paws is installed it will always look to use a credentials file stored within your supplied user directory. Paws would load your credentials and try to use them to authenticate using Keystone on Openstack side. Another option is you can delete/rename this file and set your Openstack keystone credentials using system environment variables. Usually you can get them by accessing your Openstack by web browser and go to Access & Security tab and download openstack RC file. Basically these are the variables needed: 'OS_AUTH_URL', 'OS_IDENTITY_API_VERSION', 'OS_TENANT_ID', 'OS_TENANT_NAME', 'OS_PROJECT_NAME', 'OS_USERNAME', 'OS_PASSWORD', 'OS_REGION_NAME' Access your Openstack dashboard by browser and navigate to Access & Security tab. Click at API Access and click to Download Openstack RC File button. [1] Here is an example: #!/bin/bash export OS_AUTH_URL= export OS_IDENTITY_API_VERSION=3 # replace to your tenant id without double quotes export OS_TENANT_ID= export OS_TENANT_NAME="your tenant name" export OS_PROJECT_NAME="your project name" export OS_USERNAME="username" export OS_PASSWORD="password" export OS_REGION_NAME="regionOne" if [ -z "$OS_REGION_NAME" ]; then unset OS_REGION_NAME; fi 1. Save the content above to ~/openstack-creds.sh and update the variables to your current session. 2. From terminal run the following commands. $ source ~/openstack-creds.sh $ env grep OS_ grep -v "PASSWORD" 3. DONE! You now have your Openstack credentials in your user env and is ready to run PAWS tasks if using Openstack as provider FAQ 35

40 4.9.3 Can I use PAWS just to give me a Windows and how can I access it? Yes! The idea about PAWS is much more than that but PAWS also can be used just to provision one or many Windows. Then you can access it by RDP protocol. More details can be found at guide section to provision or execute some commands in your Windows environment. To access the machine we recommend to use Remmina as remote desktop client. This comes default in Fedora repo. $ dnf provides remmina remmina rcgit.7.fc24.x86_64 : Remote Desktop Client Repo : fedora 1. Assuming you have PAWS installed and credentials.yaml and resources.yaml files, open a terminal and run: $ paws provision Once provision is complete, a new file resources.paws will be stored at your user directory /home/$user/paws. $ cat /home/$user/paws/resources.paws resources: - name: windows_2012_server public_v4: private_v4: ssh_key_file: /home/user/.ssh/id_rsa keypair: my_key_pair id: 79f0dd24-28f0-45e1-b560-a299767fa969 win_password: my_password@2016 win_username: Administrator 2. Run remmina and add the information from your system provided as the image shows below. Use the values of win_username and win_password as the login credentials. 36 Chapter 4. Finally..

41 4.9.4 What Windows images are available in my Openstack provider? You will need to have glance or nova clients installed in your machine. If not please follow steps in the following: From terminal run the following command. $ glance image-list grep -i win 4.9. FAQ 37

42 4.9.5 Why do I get an exception after removing paws and reinstalling paws? The following behavior is observed when running on a Fedora VM. If you remove paws and reinstall paws, you might find yourself seeing the following exception: Inner Exception: Problem with auth parameters. We are aware of this issue and working to provide a solution. Initial troubleshooting leads to be something around dnf removing all of paws dependencies when removing paws. Instead of just removing the paws package How can I reboot my Windows system? You have different alternatives to perform a reboot on your Windows. If it is running as VM in a Openstack you can access your Openstack dashboard by browser and issue a soft Reboot. From terminal you can run the following also. $ nova reboot 843c91ff-bb68-4cf9-85e0-8b98328c2c33 The ID above you can get from your resources.paws file. This will be stored in your user directory /home/$user/paws. The reboot could take a few minutes to have your system back online (please be patient). Another alternative is to call paws to perform the reboot. $ paws configure powershell/reboot.ps1 The reboot.ps1 script will create a scheduled task in Windows to reboot the system in 10 seconds Where can I find more PowerShell scripts? You should already be familiar with WS repository. If you are not please take a look there ws repo. A good source for PowerShell scripts Is there any difference between Windows to run in Openstack and DVD media installation for Windows? The minimum required for openstack are cloudbase-init package. This provides necessary drivers as well as customization. Other pieces have been added to allow for access such as OpenSSH (and Cygwin) for SSH, automation such as PowerShell 4.0/WinRM for Ansible, and NFS/GIT for pulling files into the environment Why Administrator account comes with no password? The default behavior of a fresh install of Windows is either to have a first-set Administrator password or Administrator account disabled. It is also best security practices to not have a common Administrator password. As Admin user is used as a user by CloudBase-init this has been continued Why I can t use a small flavor to provision a Windows? Windows has minimum resource requirements which are much higher than Linux. Usually these requirements increase each release. For example the recommended requirements should be used as a minimum for any deployed Windows instance: 38 Chapter 4. Finally..