Installing Plerion infrastructure on a Service account
Installation of Plerion infrastructure is a two-step process:
- Setting up the permissions required to run the Plerion infrastructure
- Installing the Plerion infrastructure in applicable regions
Setting up the permissions required
Steps for setting up permissions
Follow the steps below to set up the permissions required to run the Plerion infrastructure.
- On the Plerion Dashboard, Click on Tenant Settings and click on Integrations
- Search for Service Account
- Click on the
+button on the integration tile that says Workload AWS Service Account - Follow the steps in the wizard to create a new service account using AWS CloudFormation.
- Once the CloudFormation stack is created, the service account is automatically created. Returning to the Plerion Dashboard will take you to the Service Account List page.
- Click on the service account name to view the details of the service account.
- Configure regions where you want to install the Plerion infrastructure by following the steps in the next section.
Limitations
- An AWS account can only be associated with one service account.
- Service accounts cannot be shared across tenants in the same Plerion organization or across different Plerion organizations.
- The max number of service accounts that can be created in a tenant is 10.
Resources Created
Installing the CloudFormation template will create the following resources:
| Resource | Resource Type | Description |
|---|---|---|
| PlerionWorkloadAccessRole | AWS::IAM::Role | The role that will be assumed by Plerion Control Plane to manage the service account. The role grants necessary permissions to manage the appliance and clean up resources. |
| PlerionWorkloadAccessPolicy | AWS::IAM::ManagedPolicy | The policy that will be attached to the PlerionWorkloadAccessRole to allow Plerion Control Plane to manage the service account. |
| PlerionInstanceProfileRole | AWS::IAM::Role | The role that will be attached to the appliance instance to allow the instance to assume the Target account roles. |
| PlerionInstanceProfile | AWS::IAM::InstanceProfile | The instance profile that uses the PlerionInstanceProfileRole. |
| PlerionAPICallFunction | AWS::Lambda::Function | The Lambda function will be used to call the Plerion API to create the service account automatically. |
| PlerionAPILambdaExecutionRole | AWS::IAM::Role | The role that will be attached to the PlerionAPICallFunction to allow the function to call the Plerion API. |
| PlerionAPICall | Custom::PlerionAPICall | Custom resource to call the Plerion API to create the service account automatically. |
Troubleshooting
Error: PlerionInstanceProfileRole already exists in the stack
This error occurs when the AWS account is already being used as a service account in an existing Plerion organization. Currently, an AWS account can only be associated with one service account. To resolve this error, either delete the existing service account and the stack associated or use a different AWS account.
Installing the Plerion infrastructure in applicable regions
Install the Plerion infrastructure in the regions where you want to run the Plerion workload scans. Follow the steps below to install the Plerion infrastructure in applicable regions.
Steps for setting up permissions
- On the Service Account Dashboard, Click on Enable Region
- Select the region where you want to install the Plerion infrastructure and click on Launch Stack
- Follow the steps in the wizard to install the Plerion infrastructure in the selected region.
- Once the CloudFormation stack is created, the Plerion infrastructure is automatically installed in the selected region. Returning to the Service Account Dashboard shows the region as enabled.
- Repeat the steps above to install the Plerion infrastructure in other regions.
- Once the Plerion infrastructure is installed in all the regions where you want to run the Plerion workload scans, you can start linking target accounts to the service account by following the steps in the Linking target accounts to the service accounts.
Resources Created
Installing the CloudFormation template will create the following resources:
| Resource | Resource Type | Description |
|---|---|---|
| ElasticIpAZ1 | AWS::EC2::EIP | The Elastic IP address for the NAT Gateway. |
| InternetGateway | AWS::EC2::InternetGateway | Allow the VPC to access the internet. |
| NatGatewayAZ1 | AWS::EC2::NatGateway | The NAT Gateway allows the private subnet to access the internet securely |
| PlerionAPICall | Custom::PlerionAPICall | Custom resource to call the Plerion API to create the service account automatically. |
| PlerionAPICallFunction | AWS::Lambda::Function | The Lambda function will be used to call the Plerion API to create the service account automatically. |
| PlerionAPILambdaExecutionRole | AWS::IAM::Role | The role that will be attached to the PlerionAPICallFunction to allow the function to call the Plerion API. |
| PlerionApplianceAutoScalingGroup | AWS::AutoScaling::AutoScalingGroup | The AutoScaling group that will be used to manage the appliance instances. |
| PlerionApplianceLaunchLifecycleHook | AWS::AutoScaling::LifecycleHook | The lifecycle hook that will be used to manage the appliance instances. |
| PlerionApplianceLaunchTemplate | AWS::EC2::LaunchTemplate | The launch template that will be used to launch the appliance instances. |
| PlerionApplianceQueueBacklogNoInstances | AWS::CloudWatch::Alarm | The alarm that will be used to scale out the appliance instances. |
| PlerionApplianceQueueBacklogPerInstanceScaleIn | AWS::CloudWatch::Alarm | The alarm that will be used to terminate appliances when the queue has a smaller backlog |
| PlerionApplianceQueueBacklogPerInstanceScaleOut | AWS::CloudWatch::Alarm | The alarm that will be used to scale out the appliance instances when the workload scan queue has a backlog. |
| PlerionApplianceQueueNoBacklogWithInstancesScaleIn | AWS::CloudWatch::Alarm | The alarm that will be used to terminate appliances when the queue has no backlog. |
| PlerionApplianceScanQueue | AWS::SQS::Queue | The queue that will be used to manage the workload scan queue. |
| PlerionApplianceSecurityGroup | AWS::EC2::SecurityGroup | The security group that will be used to manage the appliance instances. The security group allows outbound access to allow the appliance to scan and send results |
| PlerionApplianceSubnetAZ1Private | AWS::EC2::Subnet | The private subnet that will be used to launch the appliance instances. |
| PlerionApplianceTerminationLifecycleHook | AWS::AutoScaling::LifecycleHook | The lifecycle hook that will be used to manage the appliance instances. |
| PlerionApplianceVPC | AWS::EC2::VPC | The VPC that will be used to launch the appliance instances. |
| PlerionKmsKey | AWS::KMS::Key | The KMS key that will be used to encrypt the resources being copied from the target accounts. |
| PlerionScaleInPolicy | AWS::AutoScaling::ScalingPolicy | The policy that will be used to terminate appliances when the queue has no backlog. |
| PlerionScaleOutPolicy | AWS::AutoScaling::ScalingPolicy | The policy that will be used to scale out the appliance instances when the workload scan queue has a backlog. |
| PlerionSubnetAZ1Public | AWS::EC2::Subnet | The public subnet that will be used to host the NAT Gateway. |
| RouteTableAssociationAZ1Private | AWS::EC2::SubnetRouteTableAssociation | The association between the private subnet and the private route table. |
| RouteTableAZ1PrivateCommon | AWS::EC2::RouteTable | The private route table that will be used to route traffic to the NAT Gateway. |
| RouteTableAZ1Public | AWS::EC2::RouteTable | The public route table that will be used to route traffic to the internet. |
| RouteTableAZ1PublicSubnetAssociation | AWS::EC2::SubnetRouteTableAssociation | The association between the public subnet and the public route table. |
| RouteTablePrivateCommonAZ1InternetRoute | AWS::EC2::Route | The route that will be used to route traffic to the internet via NAT Gateway. |
| RouteTablePublicAZ1InternetRoute | AWS::EC2::Route | The route that will be used to route traffic to the internet. |
| ServiceAccountOrganization | Custom::RetrieveOrganizationIdFunction | Custom resource to retrieve the organization ID from the current AWS account. |
| ServiceAccountOrganizationFunction | AWS::Lambda::Function | The Lambda function will be used to retrieve the organization ID from the current AWS account. |
| ServiceAccountOrganizationFunctionExecutionRole | AWS::IAM::Role | The role that will be attached to the ServiceAccountOrganizationFunction to allow the function to retrieve the organization ID from the current AWS account. |
| VPCGatewayAttachment | AWS::EC2::VPCGatewayAttachment | The attachment between the VPC and the Internet Gateway. |
Troubleshooting
Error: Resource handler returned message: "Resource of type 'AWS::SQS::Queue' with identifier 'plerion-appliance-scan-queue' already exists
This error occurs when the region where you are trying to install the Plerion infrastructure already has a Plerion infrastructure installed. To resolve this error, you can either delete the existing Plerion infrastructure or install the Plerion infrastructure in a different region. If the installation wasn't intended in the same region, delete the failed stack.