Getting Started with Amazon Kinesis Agent for Microsoft Windows - Amazon Kinesis Agent for Microsoft Windows

Getting Started with Amazon Kinesis Agent for Microsoft Windows

You can use Amazon Kinesis Agent for Microsoft Windows (Kinesis Agent for Windows) to collect, parse, transform, and stream logs, events, and metrics from your Windows fleet to various AWS services. The following information contains prerequisites and step-by-step instructions for installing and configuring Kinesis Agent for Windows.

Prerequisites

Before installing Kinesis Agent for Windows, ensure that you have the following prerequisites:

Setting Up an AWS Account

If you do not have an AWS account, complete the following steps to create one.

To sign up for an AWS account

  1. Open https://portal.aws.amazon.com/billing/signup.

  2. Follow the online instructions.

    Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.

To create an administrator user for yourself and add the user to an administrators group (console)

  1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

    Note

    We strongly recommend that you adhere to the best practice of using the Administrator IAM user below and securely lock away the root user credentials. Sign in as the root user only to perform a few account and service management tasks.

  2. In the navigation pane, choose Users and then choose Add user.

  3. For User name, enter Administrator.

  4. Select the check box next to AWS Management Console access. Then select Custom password, and then enter your new password in the text box.

  5. (Optional) By default, AWS requires the new user to create a new password when first signing in. You can clear the check box next to User must create a new password at next sign-in to allow the new user to reset their password after they sign in.

  6. Choose Next: Permissions.

  7. Under Set permissions, choose Add user to group.

  8. Choose Create group.

  9. In the Create group dialog box, for Group name enter Administrators.

  10. Choose Filter policies, and then select AWS managed -job function to filter the table contents.

  11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.

    Note

    You must activate IAM user and role access to Billing before you can use the AdministratorAccess permissions to access the AWS Billing and Cost Management console. To do this, follow the instructions in step 1 of the tutorial about delegating access to the billing console.

  12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to see the group in the list.

  13. Choose Next: Tags.

  14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM entities in the IAM User Guide.

  15. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.

You can use this same process to create more groups and users and to give your users access to your AWS account resources. To learn about using policies that restrict user permissions to specific AWS resources, see Access management and Example policies.

To sign up for AWS and create an administrator account

  1. If you don't have an AWS account, open https://aws.amazon.com/. Choose Create an AWS Account, and then follow the online instructions.

    Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone keypad.

  2. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  3. In the navigation pane, choose Groups, and then choose Create New Group.

  4. For Group Name, enter a name for your group, such as Administrators, and then choose Next Step.

  5. In the list of policies, select the check box next to the AdministratorAccess policy. You can use the Filter menu and the Search box to filter the list of policies.

  6. Choose Next Step. Choose Create Group, and your new group appears under Group Name.

  7. In the navigation pane, choose Users, and then choose Create New Users.

  8. In box 1, enter a user name, clear the check box next to Generate an access key for each user, and then choose Create.

  9. In the list of users, choose the name (not the check box) of the user that you just created. You can use the Search box to search for the user name.

  10. Choose the Groups tab, and then choose Add User to Groups.

  11. Select the check box next to the administrators group, and then choose Add to Groups.

  12. Choose the Security Credentials tab. Under Sign-In Credentials, choose Manage Password.

  13. Select Assign a custom password, enter a password in the Password and Confirm Password boxes, and then choose Apply.

Installing Kinesis Agent for Windows

There are two ways that you can install Kinesis Agent for Windows on Windows:

  • Install from AWS Systems Manager, a set of services for administering servers and desktops.

  • Run a PowerShell script.

Note

The following instructions occasionally use the terms KinesisTap and AWSKinesisTap. These words mean the same thing as Kinesis Agent for Windows, but you must specify them as-is when executing these instructions.

Install Kinesis Agent for Windows using AWS Systems Manager

Follow these steps to install Kinesis Agent for Windows using Systems Manager Run Command. For more information about Run Command, see AWS Systems Manager Run Command in the AWS Systems Manager User Guide. In addition to using Systems Manager Run Command, you can also use Systems Manager Maintenance Windows and State Manager to automate the deployment of Kinesis Agent for Windows over time.

Note

Systems Manager installation for Kinesis Agent for Windows is available in the AWS Regions listed in AWS Systems Manager except the following:

  • cn-north-1

  • cn-northwest-1

  • All AWS GovCloud Regions.

To install Kinesis Agent for Windows using Systems Manager

  1. Ensure that version 2.2.58.0 or later of the SSM Agent is installed on instances where you want to install Kinesis Agent for Windows. For more information, see Installing and configuring SSM Agent on Windows instances in the AWS Systems Manager User Guide.

  2. Sign in to the AWS Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  3. Open Systems Manager, and in the navigation pane, choose Run Command. Then choose Run a Command.

  4. Choose the AWS-ConfigureAWSPackage Systems Manager document.

    
      Console screenshot showing AWS-ConfigureAWSPackage document highlighted in Systems
       Manager.
  5. In the Select instances list, choose the instance or instances for Kinesis Agent for Windows installation or uninstallation, or specify a tag.

  6. For Action, choose Install.

  7. In the Name box, enter the following Amazon Resource Name (ARN) for the Kinesis Agent for Windows package:

    arn:aws:ssm:::package/AWSKinesisTap
    
      Console screenshot highlighting the choices to make in Systems Manager.
  8. For Version, keep the version as the latest, or specify a particular version.

  9. Choose Run to execute the command.

Install Kinesis Agent for Windows Using PowerShell

Use a text editor to copy the following commands into a file and save it as a PowerShell script. We use InstallKinesisAgent.ps1 in the following example.

Param( [ValidateSet("prod", "beta", "test")] [string] $environment = 'prod', [string] $version, [string] $baseurl ) # Self-elevate the script if required. if (-Not ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole] 'Administrator')) { if ([int](Get-CimInstance -Class Win32_OperatingSystem | Select-Object -ExpandProperty BuildNumber) -ge 6000) { $CommandLine = '-File "' + $MyInvocation.MyCommand.Path + '" ' + $MyInvocation.UnboundArguments Start-Process -FilePath PowerShell.exe -Verb Runas -ArgumentList $CommandLine Exit } } # Allows input to change base url. Useful for testing. if ($baseurl) { if (!$baseUrl.EndsWith("/")) { throw "Invalid baseurl param value. Must end with a trailing forward slash ('/')" } $kinesistapBaseUrl = $baseurl } else { $kinesistapBaseUrl = "https://s3-us-west-2.amazonaws.com/kinesis-agent-windows/downloads/" } Write-Host "Using $kinesistapBaseUrl as base url" $webClient = New-Object System.Net.WebClient try { $packageJson = $webClient.DownloadString($kinesistapBaseUrl + 'packages.json' + '?_t=' + [System.DateTime]::Now.Ticks) | ConvertFrom-Json } catch { throw "Downloading package list failed." } if ($version) { $kinesistapPackage = $packageJson.packages | Where-Object { $_.packageName -eq "AWSKinesisTap.$version.nupkg" } if ($null -eq $kinesistapPackage) { throw "No package found matching input version $version" } } else { $packageJson = $packageJson.packages | Where-Object { $_.packageName -match ".nupkg" } $kinesistapPackage = $packageJson[0] } $packageName = $kinesistapPackage.packageName $checksum = $kinesistapPackage.checksum #Create %TEMP%/kinesistap if not exists $kinesistapTempDir = Join-Path $env:TEMP 'kinesistap' if (![System.IO.Directory]::Exists($kinesistapTempDir)) {[void][System.IO.Directory]::CreateDirectory($kinesistapTempDir)} #Download KinesisTap.x.x.x.x.nupkg package $kinesistapNupkgPath = Join-Path $kinesistapTempDir $packageName $webClient.DownloadFile($kinesistapBaseUrl + $packageName, $kinesistapNupkgPath) $kinesistapUnzipPath = $kinesistapNupkgPath.Replace('.nupkg', '') # Calculates hash of downloaded file. Downlevel compatible using .Net hashing on PS < 4 if ($PSVersionTable.PSVersion.Major -ge 4) { $calculatedHash = Get-FileHash $kinesistapNupkgPath -Algorithm SHA256 $hashAsString = $calculatedHash.Hash.ToLower() } else { $sha256 = New-Object System.Security.Cryptography.SHA256CryptoServiceProvider $calculatedHash = [System.BitConverter]::ToString($sha256.ComputeHash([System.IO.File]::ReadAllBytes($kinesistapNupkgPath))) $hashAsString = $calculatedHash.Replace("-", "").ToLower() } if ($checksum -eq $hashAsString) { Write-Host 'Local file hash matches checksum.' -ForegroundColor Green } else { throw ("Get-FileHash does not match! Package may be corrupted.") } #Delete Unzip path if not empty if ([System.IO.Directory]::Exists($kinesistapUnzipPath)) {Remove-Item –Path $kinesistapUnzipPath -Recurse -Force} #Unzip KinesisTap.x.x.x.x.nupkg package $null = [System.Reflection.Assembly]::LoadWithPartialName('System.IO.Compression.FileSystem') [System.IO.Compression.ZipFile]::ExtractToDirectory($kinesistapNupkgPath, $kinesistapUnzipPath) #Execute chocolaeyInstall.ps1 in the package and wait for completion. $installScript = Join-Path $kinesistapUnzipPath '\tools\chocolateyInstall.ps1' & $installScript # Verify service installed. $serviceName = 'AWSKinesisTap' $service = Get-Service -Name $serviceName -ErrorAction Ignore if ($null -eq $service) { throw ("Service not installed correctly.") } else { Write-Host "Kinesis Tap Installed." -ForegroundColor Green Write-Host "After configuring run the following to start the service: Start-Service -Name $serviceName." -ForegroundColor Green }

Open an elevated command prompt window. In the directory where the file was downloaded, use the following command to run the script:

PowerShell.exe -File ".\InstallKinesisAgent.ps1"

To install a specific version of Kinesis Agent for Windows, add the -version option:

PowerShell.exe -File ".\InstallKinesisAgent.ps1" -version "version"

Replace version with a valid Kinesis Agent for Windows version number. For version information, see the kinesis-agent-windows repository on GitHub.

There are many deployment tools which can remotely execute PowerShell scripts. They can be used to automate the installation of Kinesis Agent for Windows on fleets of servers or desktops.

Configuring and Starting Kinesis Agent for Windows

After installing Kinesis Agent for Windows, you must configure and start the agent. After that, no further operation intervention should be required.

To configure and start Kinesis Agent for Windows

  1. Create and deploy a Kinesis Agent for Windows configuration file. This file configures sources, sinks, and pipes, along with other global configuration items.

    For more information about Kinesis Agent for Windows configuration, see Configuring Amazon Kinesis Agent for Microsoft Windows.

    For complete configuration file examples that you can customize and install, see Kinesis Agent for Windows Configuration Examples.

  2. Open an elevated PowerShell command prompt window, and start Kinesis Agent for Windows using the following PowerShell command:

    Start-Service -Name AWSKinesisTap