Amazon S3 Bucket

This topic provides reference information about the Amazon S3 (csb-aws-s3-bucket) service.

It details the plans, configuration parameters, and binding credentials.

Plan Configuration Parameters

When configuring Cloud Service Broker for AWS you can add additional plans. For how to configure plans, see Configure Services with Cloud Service Broker for AWS.

The following table lists parameters which can only be configured for additional plans:

Parameter name	Values	Default	Required
`name`	The plan name.	n/a	Yes
`id`	A unique GUID.	n/a	Yes
`description`	Description of the new plan.	n/a	Yes
`free`	When false, service instances of this service plan have a cost.	true	No
`bindable`	Specifies whether service instances of the service plan can bind to applications.	true	No
`plan_updateable`	Whether the plan supports upgrading, downgrading, or sidegrading to another version.	true	No
`metadata.displayName`	Name to use when displaying the plan in the Marketplace.	n/a	No
`metadata.bullets`	List of bullet points to display in Apps Manager.	n/a	No

You can also add any of the parameters listed in the Configuration Parameters section to your plan.

Note
If you set a parameter at plan level, developers cannot change the value when creating or updating service instances.

Configuration Parameters

You can provision a service by running:

cf create-service csb-aws-s3-bucket PLAN-NAME SERVICE-INSTANCE-NAME -c '{"PARAMETER-NAME": "PARAMETER-VALUE"}

You can update the configuration parameters for a service instance by running:

cf update-service SERVICE-INSTANCE-NAME -c '{"PARAMETER-NAME": "PARAMETER-VALUE"}'

The following table lists the parameters that you can configure, by using the -c flag, when provisioning or updating a csb-aws-s3-bucket service. The Operation column displays whether a parameter is supported for both provision and update, or for provision only:

Parameter name	Type	Description	Default	Operation
`bucket_name`	String	The name of the bucket to create	`csb-INSTANCE-ID`	provision
`acl`	String	S3 bucket access control list (ACL). For more information, see the AWS documentation. ACLs are automatically deactivated if boc_object_ownership is set to `BucketOwnerEnforced`. Permitted values: `null`, `private`, `public-read`, `public-read-write`, `aws-exec-read`, `authenticated-read`, `bucket-owner-read`, `bucket-owner-full-control`, and `log-delivery-write`	`null`	provision
`enable_versioning`	Boolean	Activate bucket versioning. Versioning is automatically active if Amazon S3 Object Lock is activated.	`false`	provision and update
`region`	String	This is the AWS region to deploy the service in. For more information about available regions, see the AWS documentation.	`us-west-2`	provision
`boc_object_ownership`	String	S3 Bucket Ownership Controls. Permitted values: `BucketOwnerPreferred`, `ObjectWriter`, and `BucketOwnerEnforced`. Setting this property to `BucketOwnerEnforced` deactivates ACLs. For more information, see the AWS documentation.	`BucketOwnerEnforced`	provision
`sse_default_algorithm`	String	The server-side encryption algorithm to use to automatically encrypt new objects stored in this bucket. Valid values are `AES256` to use Amazon S3-managed keys (SSE-S3) and `aws:kms` to use an AWS Key Management Service key (SSE-KMS). For more information about server-side encryption, see the AWS documentation.	`null`	provision and update
`sse_default_kms_key_id`	String	The AWS Key Management Service (KMS) key ID used for the Amazon S3 server-side encryption, which uses AWS Key Management Service (SSE-KMS). To use this parameter, set the value of `sse_default_algorithm` to `aws:kms`. Changing the `sse_default_kms_key` doesn't reencrypt existing objects, so any new binding won't be able to read those objects, unless you add the old KMS key to the `sse_extra_kms_key_ids`. Also, existing bindings continue to use the previous `sse_default_kms_key_id`. If you want all bindings for an instance to use the latest `sse_default_kms_key_id`, you must delete and recreate them.	`null`	provision and update
`sse_extra_kms_key_ids`	String	A comma-separated list of additional custom KMS key IDs that can be used to encrypt and decrypt objects in the bucket. The list of `sse_extra_kms_key_ids` is relevant even if server-side encryption is disabled, because apps can use any KMS key from this list to selectively encrypt new objects and read objects encrypted with them.	`null`	provision and update
`sse_bucket_key_enabled`	Boolean	Sets whether to use Amazon S3 Bucket Keys for SSE-KMS. For more information about Bucket Keys, see the AWS documentation.	`false`	provision and update
`pab_block_public_acls`	Boolean	Sets whether Amazon S3 blocks public ACLs for the bucket. For more information, see the AWS documentation.	`false`	provision and update
`pab_block_public_policy`	Boolean	Sets whether Amazon S3 blocks public bucket policies for the bucket. For more information, see the AWS documentation.	`false`	provision and update
`pab_ignore_public_acls`	Boolean	Sets whether Amazon S3 ignores public ACLs for the bucket. For more information, see the AWS documentation.	`false`	provision and update
`pab_restrict_public_buckets`	Boolean	Sets whether Amazon S3 restricts public bucket policies for the bucket. For more information, see the AWS documentation.	`false`	provision and update
`ol_enabled`	Boolean	Sets whether to activate Amazon S3 Object Lock. This stores objects using a write-once-read-many (WORM) model. For more information about Object Lock, see the AWS documentation.	`false`	provision
`ol_configuration_default_retention_enabled`	Boolean	Sets whether the bucket has an active Object Lock `configuration`. To activate Object Lock for a new bucket, see the `ol_enabled` parameter. For more information about Object Lock, see the AWS documentation.	`null`	provision and update
`ol_configuration_default_retention_mode`	String	The default retention mode for objects placed in the bucket. If you set this parameter, you must also set the `ol_configuration_default_retention_days` or `ol_configuration_default_retention_years` parameter. To activate Object Lock for a new bucket, see the `ol_enabled` parameter. For more information about Object Lock, see the AWS documentation.	`null`	provision and update
`ol_configuration_default_retention_days`	Number	The default fixed number of days of retention for objects placed in the bucket. This property is only required if you have set `ol_configuration_default_retention_mode`, but have not set `ol_configuration_default_retention_years`. To activate Object Lock for a new bucket, see the `ol_enabled` parameter. For more information about Object Lock, see the AWS documentation.	`null`	provision and update
`ol_configuration_default_retention_years`	Number	The default fixed number of years of retention for objects placed in the bucket. This property is only required if you have set `ol_configuration_default_retention_mode`, but have not set `ol_configuration_default_retention_days`. To activate Object Lock for a new bucket, see the `ol_enabled` parameter. For more information about Object Lock, see the AWS documentation.	`null`	provision and update
`allowed_aws_vpc_id`	String	The VPC ID to restrict access exclusively to the designated VPC. E.g: `vpc-01362976bd10dc099` Read more information about the necessary AWS infrastructure to be able to use this AWS characteristic. here	`""`	provision and update
`require_tls`	Boolean	Whether the bucket explicitly denies access to HTTP requests. If enabled, the bucket only accepts requests sent through HTTPS.	`false`	provision and update
`aws_access_key_id`	String	The AWS Access Key to use for an instance.	The value the operator entered for AWS Access Key in Ops Manager	provision and update
`aws_secret_access_key`	String	The corresponding secret for the AWS Access Key to use for an instance.	The value the operator entered for AWS Secret Access Key in Ops Manager	provision and update

When using S3 Object Lock, take your encryption technique into consideration. For example, if you are using server-side encryption with AWS KMS keys, consider how the possible deletion of the key might interact with S3 Object Lock.

When creating a bucket with Object Lock activated, Amazon S3 automatically activates versioning for the bucket. To avoid differences between the local state and the AWS state, Cloud Service Broker for AWS activates versioning when enabling Object Lock.

Binding Parameters

You can bind a service by running:

cf bind-service APP-NAME SERVICE-INSTANCE-NAME --binding-name BINDING-NAME -c '{"PARAMETER-NAME": "PARAMETER-VALUE"}'

The following table lists the parameters that you can configure, using the -c flag, when binding to a csb-aws-s3-bucket service:

Parameter Name	Type	Description	Default
`aws_access_key_id`	String	The AWS Access Key to use for an instance	The value the operator entered for AWS Access Key in Ops Manager
`aws_secret_access_key`	String	The corresponding secret for the AWS Access Key to use for an instance	The value the operator entered for AWS Secret Access Key in Ops Manager

Binding Credentials

The format for binding credentials for Amazon S3 Bucket is as follows:

{
    "arn" : "BUCKET-ARN",
    "bucket_domain_name" : "BUCKET-FQDN",
    "region" : "BUCKET-REGION",
    "bucket_name" : "BUCKET-NAME",
    "access_key_id" : "ACCESS-KEY-FOR-BUCKET",
    "secret_access_key" : "SECRET-KEY-FOR-BUCKET"
}

Previously Provided Pre-configured Plans

The following table lists the previously provided plans for the csb-aws-s3-bucket service:

Plan	Description
private	Private S3 bucket
public-read	Publicly readable S3 bucket

To keep these plans in this version of the broker, add them through the tile as custom plans. For how to configure plans through the tile, see Configure Services with Cloud Service Broker for AWS.

Add the following block to keep the private plan:

{
    "name": "private",
    "id": "8938b4c0-d67f-4c34-9f68-a66deef99b4e",
    "description": "Private S3 bucket",
    "acl": "private",
    "boc_object_ownership": "ObjectWriter",
    "metadata": {
        "displayName": "Private",
        "bullets": ["Private ACL", "ObjectWriter ownership"]
    }
}

Add the following block to keep the public-read plan:

  {
      "name": "public-read",
      "id": "04317eaa-11ac-4c5f-b77f-eb005fe977fe",
      "description": "Public-read S3 bucket",
      "acl": "public-read",
      "boc_object_ownership": "ObjectWriter",
      "metadata": {
        "displayName": "Public Read",
        "bullets": ["Public read ACL", "ObjectWriter ownership"]
      }
  }

VPC Endpoint

Why a VPC Endpoint is Needed: VPC Endpoints are crucial in enhancing the security and efficiency of accessing AWS services from within your Amazon Virtual Private Cloud (Amazon VPC). By using VPC endpoints, the network traffic between your VPC and AWS services can be routed internally within the AWS network, avoiding the public Internet. When traffic is routed internally withing the AWS network, restrictions can be added to the user’s policies to ensure that only users connecting from within the specific VPCs can access the S3 bucket. This reduces exposure to external threats and decreases latency by providing a direct network route.

In scenarios where sensitive data like backups or confidential files are stored on S3, using a VPC endpoint ensures that this data is not inadvertently exposed to the Internet. This is especially relevant to ensure all data interactions happen within a controlled and secure environment.

The Cloud Service Broker for AWS creates IAM users with a policy configuration to specify VPC access, enhancing security controls at the user level, but this configuration is not enough to ensure secure access to the S3 bucket. In order to ensure secure access to the S3 bucket, the VPC endpoint must be properly configured.

Caution The Cloud Service Broker for AWS won't be responsible for creating or maintaining the VPC Endpoint. This responsibility lies with the customer.

Here are some advantages of the current approach:

Enhanced Security Control: By allowing access only from specific VPCs, we mitigate the risk of data breaches from leaked credentials. Access from unauthorized locations is inherently blocked, providing robust data protection.
Customization and Flexibility: Users have the flexibility to define and adjust their security settings based on specific VPC IDs, tailoring the security measures to their operational needs.
Clear Responsibility: This approach clarifies that the responsibility for managing VPC endpoints and ensuring correct configurations rests with the users and not in CSB, promoting better governance and adherence to security policies. Security requirements depend on the specific use case in the organization, and this approach allows for customization to meet those requirements.

Example of a VPC Endpoint Policy: To facilitate the secure and restricted access to S3 services when using CSB, the following VPC endpoint policy can be used. This policy ensures that only the traffic originating from the specified VPC and certain IAM users prefixed with csb-* can access the resources.

Note
Replace <ALLOWED_AWS_VPC_ID> with the VPC ID passed as parameter allowed_aws_vpc_id when configuring the S3 bucket. Replace <AWS-ACCOUNT-ID> with the AWS account ID used by CSB. This is the account ID that CSB uses and needed to allow managing S3 buckets.

{
  "Statement": [
    {
      "Action": "*",
      "Effect": "Allow",
      "Resource": "*",
      "Principal": "*",
      "Condition": {
        "StringEquals": {
          "aws:sourceVpc": "<ALLOWED_AWS_VPC_ID>"
        },
        "StringLike": {
          "aws:username": "csb-*"
        }
      }
    },
    {
      "Action": "*",
      "Effect": "Allow",
      "Resource": "*",
      "Principal": {
        "AWS": "arn:aws:iam::<AWS-ACCOUNT-ID>:root"
      },
      "Condition": {
        "StringEquals": {
          "aws:sourceVpc": "<VPC-ID>"
        }
      }
    }
  ]
}

In this policy:

The first statement allows any actions (*) from any principals (*) on any resources (*), provided the request originates from the specified VPC (aws:sourceVpc) and involves users whose usernames start with csb-*. CSB creates IAM users with the prefix csb-*.
The second statement specifically allows root access from the specified AWS account, ensuring that administrative tasks can be performed without restrictions, but still only from within the designated VPC.

This configuration ensures that even if credentials were leaked, they would not be usable outside the specified VPC, significantly enhancing the security of your AWS environment.