{"id":15192237,"url":"https://github.com/powershell/awsdsctoolkit","last_synced_at":"2025-10-02T07:30:26.772Z","repository":{"id":65985510,"uuid":"56193273","full_name":"PowerShell/AwsDscToolkit","owner":"PowerShell","description":"AWS DSC Toolkit","archived":true,"fork":false,"pushed_at":"2017-01-20T01:12:51.000Z","size":67,"stargazers_count":10,"open_issues_count":3,"forks_count":11,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-01-21T12:35:57.364Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PowerShell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-13T23:44:00.000Z","updated_at":"2023-01-28T10:25:06.000Z","dependencies_parsed_at":"2023-02-19T18:30:34.323Z","dependency_job_id":null,"html_url":"https://github.com/PowerShell/AwsDscToolkit","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/PowerShell/AwsDscToolkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FAwsDscToolkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FAwsDscToolkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FAwsDscToolkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FAwsDscToolkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PowerShell","download_url":"https://codeload.github.com/PowerShell/AwsDscToolkit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PowerShell%2FAwsDscToolkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277974402,"owners_count":25908396,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-02T02:00:08.890Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-27T21:20:20.264Z","updated_at":"2025-10-02T07:30:26.461Z","avatar_url":"https://github.com/PowerShell.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS DSC Toolkit\n\nUse of the AWS DSC Toolkit is subject to this [privacy agreement](http://go.microsoft.com/fwlink/p/?linkid=131004\u0026amp;clcid=0x409).\n\nThis module is currently in preview.  \nIt is provided as is and is not supported through any Microsoft support program or service.\n\nThis project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).\nFor more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.\n\n## Description\nThis module allows you to register AWS EC2 instances as DSC Nodes in Azure Automation.\nYou can then control your EC2 instances in Azure Automation using PowerShell DSC configurations.\n\n## Releases\n\n### Unreleased\n\n### 0.5.0.0\n- Fixed messed up module manifest\n\n### 0.4.0.0\n- Refined depedency on AzureRM module. Module manifest now only specifies AzureRM.Automation and AzureRM.Profile as required modules.\n- Removed KeyPair parameter from tests.\n- Added ExtensionVersion parameter to tests.\n- Added DataCollection parameter to Register-EC2Instance. This new parameter allows you to opt-out from Microsoft telemetry collection.\n\n### 0.3.0.0\n- Fixed variable typo for AWS credential and region in Set-IAMInstanceProfileForRegistration.\n\n### 0.2.0.0\n- Modified encryption key selection. Register-EC2Instance will now select the first key that the provided instance profile has access to rather than just the first key available.\n\n### 0.1.0.0\n- Initial release.\n\n## Installation\nThe AWS DSC Toolkit is available on the [PowerShell Gallery](https://www.powershellgallery.com/packages/AwsDscToolkit).  \nYou can install it using PSGet:\n```powershell\nInstall-Module AwsDscToolkit\n```\n\n## Credentials and Region\nTo use the cmdlets in this module, you will need to log in to your Azure account and provide AWS credentials as well as an AWS region.\nYou can easily log into your Azure account with this command alias:\n```powershell\nAdd-AzureRmAccount\n```\nBy default, the cmdlets in this module will use the AWS credentials profile with the name 'default'.\nTo specify the AWS credentials profile with the name 'default':\n```powershell\nSet-AWSCredentials -AccessKey 'MyAccessKey' -SecretKey 'MySecretKey' -StoreAs 'default'\n```\nTo set the default AWS region:\n```powershell\nSet-DefaultAWSRegion 'myRegion'\n```\nYou can also specify your AWS credentials and region through the AwsAccessKey, AwsSecretKey, AwsProfile, and AwsRegion parameters on each of the cmdlets.\n\n## Register-EC2Instance\n### Registering a New Instance\nBy default, Register-EC2Instance will create a t2.micro instance with the latest version of the AMI (Amazon Machine Image) with the name WINDOWS_2012R2_BASE.\n\nTo register a new instance to Azure Automation, use the Register-EC2Instance cmdlet with the New flag:\n```powershell\nRegister-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -New -InstanceProfile_Name 'MyInstanceProfileName' -SecurityGroup 'MySecurityGroup'\n```\nYou can also pass in additional EC2 parameters, for more imformation on these parameters see the [EC2 documentation](http://docs.aws.amazon.com/powershell/latest/reference/index.html?page=New-EC2Instance.html\u0026tocid=New-EC2Instance)\n\nFor example to pass in a specific subnet and security group:\n```powershell\nRegister-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -New -InstanceProfile_Name 'MyInstanceProfileName' -SecurityGroupId 'MySecurityGroup-Id' -SubnetId 'MySubnet-ID'\n```\n**Note:** If you want to pass in a SecurityGroup, you can only pass in the SecurityGroupId if used in conjunction with SubnetID.\n\nYou can also provide as exisiting SecurityKey:\n\n```powershell\nRegister-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -New -InstanceProfile_Name 'MyInstanceProfileName' -SecurityGroupId 'MySecurityGroup-Id' -SubnetId 'MySubnet-ID' -KeyName 'MyKeyName'\n```\n\nWhen the New flag is set, this cmdlet acts as a proxy for the AWS cmdlet New-EC2Instance. All parameters of New-EC2Instance are included in Register-EC2Instance -New except for those pertaining to user data (UserData, UserDataFile).\n\nYour new instance must have access to an AWS encryption key through the instance profile with the name specified by the InstanceProfile_Name parameter. For more information on this see the 'IAM Instance Profile Requirements' section below.\n\nYou new instance must also have a security group which will allow it to download the AWS DSC Bootstrapper and talk to Azure Automation. The default security create by this command will suffice:\n```powershell\nNew-EC2SecurityGroup -GroupName 'MySecurityGroup' -Description 'Security group for registration to Azure Automation'\n```\nThis creates a default security with all outbound ports open and all inbound ports closed.\n\n### Registering an Existing Instance\nTo register an existing instance to Azure Automation, use the Register-EC2Instance cmdlet with the InstanceId parameter:\n```powershell\nRegister-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId'\n```\n\nUnfortunately, not all existing EC2 instances can be registered due to limitation with AWS permissions on existing instances. For more information on this, see the 'Checking If an Existing Instance Can Register' section.\n\n### Specifying a DSC Node Configuration at Registration Time\nYou can specify a DSC Node configuration on your Azure Automation account to apply to an EC2 instance immediately after registration using the NodeConfigurationName parameter:\n```powershell\nRegister-EC2Instance -AzureAutomationAccount 'MyAutomationAccount' -InstanceId 'ExistingInstanceId' -NodeConfigurationName 'MyConfiguration.Webserver'\n```\n\nYou can also modify the behavior of DSC immediately after registration using the ConfigurationMode, ConfigurationModeFrequencyMins, RefreshFrequencyMins, RebootNodeIfNeeded, AllowModuleOverwrite, and ActionAfterReboot parameters.\n\nBy default these are set to the following values: \n\n| Parameter | Default Value | \n| --- | --- | \n| ConfigurationMode | 'ApplyAndMonitor' |\n| ConfigurationModeFrequencyMins | 15 | \n| RefreshFrequencyMins | 30 | \n| RebootNodeIfNeeded | False | \n| AllowModuleOverwrite | False | \n| ActionAfterReboot | 'ContinueConfiguration' | \n\nFor more information on these values, see the [PowerShell DSC documentation](https://msdn.microsoft.com/en-us/powershell/dsc/metaconfig).\n\n## Test-EC2InstanceRegistration\nThis cmdlet will return an EC2InstanceRegistrationStatus enum value.\nThis new type is included with the module.\nThe 4 possible values are:\n- CannotRegister\n- NotReadyToRegister\n- ReadyToRegister\n- Registered\n\n### Checking If an Existing Instance Can Register\nTo check if your EC2 instance can register, use the Test-EC2InstanceRegistration cmdlet:\n```powershell\nTest-EC2InstanceRegistration -InstanceId 'ExistingInstanceId'\n```\n\nIf an Azure Automation account is not provided, this cmdlet will return CannotRegister, NotReadyToRegister, or ReadyToRegister.\n\n#### CannotRegister \nThis value indicates that your instance does not have an IAM instance profile. AWS currently does not allow you to assign an IAM instance profile to an existing EC2 instance. To work around this, you can create an image of your existing instance and then create a new EC2 instance with an IAM instance profile from that image.\n\n#### NotReadyToRegister\nThis value indicates that your instance has an IAM instance profile, but the instance profile does not have the correct permissions to register this instance. For more information on how to fix your IAM instance profile, see the 'IAM Instance Profile Requirements' section below.\n\nBefore a new instance created by Register-EC2Instance has finished registering, it may also return the NotReadyToRegister status since new instances do not require permission to use the AWS Run Commmand feature.\n\n#### ReadyToRegister\nThis value indicates that the instance is correctly configured to register.  \nBefore an existing instance has finished registering, it should return ReadyToRegister.\n\n### Checking If an Instance is Registered\nTo check if an instance is registered with your Azure Automation account, use the Test-EC2InstanceRegistration cmdlet with an Azure Automation account specified:\n```powershell\nTest-EC2InstanceRegistration -AzureAutomationAccount 'MyAzureAutomationAccount' -InstanceId 'MyInstanceId'\n```\nThis cmdlet will return an EC2InstanceRegistrationStatus enum value.\nIf the instance is registered, this value will be Registered.\nIf the instance is not registered or is still in the process of registering, it may return NotReadyToRegister or ReadyToRegister.\n\nPlease keep in mind that it usually takes about 10-20 minutes for an instance to register.\nIf you are using an instance that has an older WMF, it may take longer since the instance's WMF will need to be updated to work with Azure Automation.\n\n#### Registered\nThis value indicates that the instance is registered as a DSC node with the provided Azure Automation account.\nTest-EC2InstanceRegistration will not check for the Registered status unless you provide an Azure Automation account.\n\n## IAM Instance Profile Requirements\nIn order to register any EC2 instance to Azure Automation, the Register-EC2Instance cmdlet will retrieve the registration key associated with your Azure Automation account. To keep this key safe, the cmdlet encrypts your key using an AWS encryption key associated with your AWS account. Any EC2 instances registering to Azure Automation Register-EC2Instance cmdlet must also have access to this encryption key in order to decrpyt your RegistrationKey. This access is given through an IAM instance profile.\n\nIn order to register an existing EC2 instance, the Register-EC2Instance cmdlet uses the AWS Run Command feature.\nThis means that to register an existing instance, the attached instance profile must have permission to use the Run Command feature. This is not required for instances created by the Register-EC2Instance cmdlet\n\n### Set-IAMInstanceProfileForRegistration\nOnce you have an encryption key on your AWS account, the Set-IAMInstanceProfileForRegistration cmdlet can create or modify an IAM instance profile to have the correct permissions to register a new or existing EC2 instance.\n\nMore information on how to create an encryption key is available [here](http://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html).\n\nTo modify or create a new IAM instance profile with the correct key access to register a new EC2 instance:\n```powershell\nSet-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'\n```\nThis will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile.\n\nIf an IAM instance profile with the name provided does not exist, this cmdlet will create one.\nIf the IAM instance profile with the name provided does exist, the profile will be modified with the proper permissions for registration.\n\nThe Set-IAMInstanceProfileForRegistration cmdlet will only provide access to Run Command when the ExistingInstance flag is set.\nFor example, to modify or create an IAM instance profile with access to encryption keys and permission to use run command:\n```powershell\nSet-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance\n```\nIf access has not already been granted, this will modify the key policy attached to one of your encryption keys to allow access by the specified instance profile. This will also attached the AWS managed policy called 'AmazonEC2RoleforSSM' to a role in the specified instance profile.\n\nThis cmdlet returns an AWS IAM instance profile.\n\n### Test-IAMInstanceProfileForRegistration\nTo check if an IAM instance profile has the correct permissions to register a new EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet:\n```powershell\nTest-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName'\n```\n\nTo check if an IAM instance profile has the correct permissions to register an existing EC2 Instance, you can use the Test-IAMInstanceProfileForRegistration cmdlet with the ExistingInstance flag:\n```powershell\nTest-IAMInstanceProfileForRegistration -Name 'MyInstanceProfileName' -ExistingInstance\n```\n\nThis cmdlet will return a boolean value.\nThe permission to use Run Command may be removed from the instance profile once the instance has registered.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowershell%2Fawsdsctoolkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpowershell%2Fawsdsctoolkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpowershell%2Fawsdsctoolkit/lists"}