# AWS Marketplace Quickstart

This guide walks you through purchasing AGENTIC STAR from AWS Marketplace and completing the deployment. After subscribing, you launch a CloudFormation stack from the AWS Marketplace launch page; the nested CloudFormation templates then provision the VPC, EKS cluster, RDS, S3 buckets, and install the Kubernetes applications automatically.

## Prerequisites

- An AWS account
- IAM permissions to create and manage the following AWS resources via CloudFormation:
  <!-- -->
  - EKS, EC2, VPC, IAM, RDS, S3, CloudFormation, Bedrock
- **Sufficient EC2 vCPU quota** (see below)
- **A Bedrock Guardrails-supported region selected for the security stack, plus Bedrock model access requested in that region** (see below)
- **Service-linked roles created in advance** (see below — they are auto-created on first use, but pre-creating reduces first-deploy time)
- `kubectl` and AWS CLI v2 installed locally to connect to the cluster after deployment

### Bedrock Guardrails (`SecurityRegion` parameter)

This product uses **Amazon Bedrock Guardrails + Amazon Comprehend** for Content Safety and PII inspection. The CloudFormation `SecurityRegion` parameter (default `ap-northeast-1`) controls where these services run; it is decoupled from your main infrastructure region (EKS / RDS) so you can keep security inspection close to your data residency boundary.

#### Supported regions for `SecurityRegion`

Enforced by `AllowedValues` in `main-template.yaml`:

`ap-northeast-1` (Tokyo) / `ap-northeast-2` (Seoul) / `ap-south-1` (Mumbai) / `ap-southeast-1` (Singapore) / `ap-southeast-2` (Sydney) / `us-east-1` (N. Virginia) / `us-east-2` (Ohio) / `us-west-2` (Oregon) / `ca-central-1` (Canada Central) / `eu-central-1` (Frankfurt) / `eu-west-1` (Ireland) / `eu-west-2` (London)

#### Request Bedrock model access in advance

In the AWS Console for your `SecurityRegion`, go to **Bedrock → Model access** and request access to the foundation models used by Guardrails (at minimum the **Anthropic Claude** family). Approval typically takes minutes to hours.

#### Verify availability before deploying

```bash
# Verify Bedrock responds
aws bedrock list-foundation-models --region ap-northeast-1 --max-results 1

# Verify Comprehend responds
aws comprehend list-endpoints --region ap-northeast-1
```

Both commands should return JSON without errors before you start the deployment.

### Pre-create Service-linked Roles

These service-linked roles are auto-created on first use, but pre-creating them avoids first-deploy delays. If a role already exists, you will see `Already exists` — ignore it.

```bash
aws iam create-service-linked-role --aws-service-name eks.amazonaws.com         || true
aws iam create-service-linked-role --aws-service-name rds.amazonaws.com         || true
aws iam create-service-linked-role --aws-service-name elasticloadbalancing.amazonaws.com || true
```

### EC2 vCPU Quota

EKS nodes can only be launched within your account's per-region EC2 vCPU quota (**Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances** in Service Quotas). If the quota is too low, creating the node groups or adding nodes fails, and the stack creation fails only after a long time. New accounts may have a small default for this quota, so make sure the following amount is available in the target region before you start the deployment.

| Quota                                                                | Required                                                                                                                                                            |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Running On-Demand Standard (A, C, D, H, I, M, R, T, Z) instances** | At least 16, recommended 32 (default `m5.2xlarge` (8 vCPUs) × 1 System node + 1 User node = 16 vCPUs; the recommended value lets the autoscaler add two more nodes) |

- This is what the installation of the application suite needs (total CPU requests are about 8 vCPUs, plus about 0.6 vCPU of DaemonSets per node). As agent executions grow, the autoscaler adds nodes (default maximum: 8 System + 10 User), so leave headroom according to your workload
- All instance types selectable in EKS Advanced Settings (`t3.*` / `m5.*`) count against this quota. If you change the node count or instance type, secure the total vCPUs accordingly
- RDS for PostgreSQL does not consume this quota

#### Check the Quota

```bash
# Show the limit in the target region (example: N. Virginia)
aws service-quotas get-service-quota --service-code ec2 \
  --quota-code L-1216C47A --region us-east-1 \
  --query 'Quota.[QuotaName,Value]' --output table
```

Current usage is shown as **Utilization** under **Service Quotas** → **Amazon Elastic Compute Cloud (Amazon EC2)** → the quota above in the AWS Console. Confirm that the limit minus the usage is at least the required amount.

#### Increase the Quota

Request a new limit with **Request increase at account level** on the same screen, or with the CLI as shown below. Approval can take time, so complete it before the deployment.

```bash
aws service-quotas request-service-quota-increase --service-code ec2 \
  --quota-code L-1216C47A --desired-value 32 --region us-east-1
```

## Steps

### 1. Subscribe to AGENTIC STAR Advanced on AWS Marketplace

Search for "AGENTIC STAR Advanced" on [AWS Marketplace](https://aws.amazon.com/marketplace) and click **\[Continue to Subscribe]**. After accepting the terms, **\[Continue to Configuration]** becomes available.

### 2. Choose Delivery Method and Region

Click **\[Continue to Configuration]** and select the following:

| Field                | Value                                     |
| -------------------- | ----------------------------------------- |
| **Delivery Method**  | CloudFormation                            |
| **Software Version** | The latest version                        |
| **Region**           | The deployment region (see prerequisites) |

Then click **\[Continue to Launch]**.

### 3. Launch CloudFormation

On the **Launch this software** page, choose **"Launch CloudFormation"** under Choose Action and click **\[Launch]**. You will be redirected to the AWS CloudFormation console with `main-template.yaml` pre-loaded.

> **note**
>
> The `Amazon EC2 Image ID` (`ImageId` parameter) is set automatically by AWS Marketplace. **Do not change it.** The `MPS3BucketName`, `MPS3BucketRegion`, and `MPS3KeyPrefix` parameters are also set automatically by AWS Marketplace and must not be changed.

### 4. Stack Name

| Field          | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| **Stack name** | Identifier for the CloudFormation stack (must be unique within the region) |

### 5. General Settings

| Parameter                  | Description                                    | Default       | Constraints                                                                                                                                                                 |
| -------------------------- | ---------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Environment Name**       | Identifier used as a prefix for resource names | `agenticstar` | 3–21 characters, must start with a lowercase letter; lowercase alphanumeric and hyphens                                                                                     |
| **Administrator Email**    | Email address of the initial administrator     | —             | Valid email address format (up to 254 characters)                                                                                                                           |
| **Administrator Password** | Password for the initial administrator         | —             | 12–128 characters, must include at least one uppercase letter, one lowercase letter, one digit, and one special character. Only `@$!%*?&` can be used as special characters |
| **Primary Language**       | UI display language                            | `ja`          | `ja` / `en` / `fr` / `es` / `th` / `ar` / `id` / `zh-Hans` / `zh-Hant` / `pt-BR` / `de-DE` / `it-IT` / `vi` / `ko`                                                          |

### 6. PostgreSQL Settings

| Parameter                                           | Description                          | Default          | Constraints                                                              |
| --------------------------------------------------- | ------------------------------------ | ---------------- | ------------------------------------------------------------------------ |
| **PostgreSQL Instance Identifier**                  | RDS instance identifier              | `marketplace-db` | 1–63 characters                                                          |
| **PostgreSQL Instance Class (default recommended)** | RDS instance class                   | `db.m5.large`    | `db.m5.large` / `db.m5.xlarge` / `db.m5.2xlarge`                         |
| **PostgreSQL Multi-AZ Deployment**                  | Whether to use a Multi-AZ deployment | `false`          | `true` / `false`                                                         |
| **PostgreSQL Admin Username**                       | Database administrator username      | `db_admin`       | 1–16 characters                                                          |
| **PostgreSQL Admin Password**                       | Database administrator password      | —                | 8–128 characters. The characters `/`, `@`, `"`, and space cannot be used |

> **info**
>
> The DB engine (PostgreSQL 16.10) and storage (32 GiB with autoscaling up to 500 GiB) are fixed in the template.

### 7. EKS Advanced Settings

Two managed node groups are configured: a System Node Group and a User Node Group.

**System Pool**

| Parameter                        | Default      | Range / Allowed Values                                                            |
| -------------------------------- | ------------ | --------------------------------------------------------------------------------- |
| System Pool VM Size              | `m5.2xlarge` | `t3.medium` / `t3.large` / `m5.large` / `m5.xlarge` / `m5.2xlarge` / `m5.4xlarge` |
| System Pool Node Count (Desired) | 1            | 1–20                                                                              |
| System Pool Min Count            | 1            | 1–20                                                                              |
| System Pool Max Count            | 8            | 1–20                                                                              |

**User Pool**

| Parameter                      | Default      | Range / Allowed Values                                                            |
| ------------------------------ | ------------ | --------------------------------------------------------------------------------- |
| User Pool VM Size              | `m5.2xlarge` | `t3.medium` / `t3.large` / `m5.large` / `m5.xlarge` / `m5.2xlarge` / `m5.4xlarge` |
| User Pool Node Count (Desired) | 1            | 1–20                                                                              |
| User Pool Min Count            | 1            | 1–20                                                                              |
| User Pool Max Count            | 10           | 1–20                                                                              |

> **caution**
>
> The default (`m5.2xlarge` × 1 System node + 1 User node) is the minimum configuration for installing the application suite. Selecting a smaller instance type may cause resource shortages. If you change the node count or instance type, also secure the [EC2 vCPU quota](#vcpu-quota) accordingly.

### 8. Datadog Settings (Optional)

Configure these parameters if you want to enable Datadog integration.

| Parameter                      | Description                                           | Default             | Allowed Values                                                                                     |
| ------------------------------ | ----------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| **Enable Datadog Integration** | Enables Datadog integration                           | `false`             | `true` / `false`                                                                                   |
| **Datadog API Key**            | Datadog API key (required when set to `true`)         | (empty)             | —                                                                                                  |
| **Datadog Application Key**    | Datadog application key (required when set to `true`) | (empty)             | —                                                                                                  |
| **Datadog Site**               | Datadog site                                          | `ap1.datadoghq.com` | `ap1.datadoghq.com` / `datadoghq.com` / `us3.datadoghq.com` / `us5.datadoghq.com` / `datadoghq.eu` |

### 9. Acknowledge IAM and Create the Stack

In the **Capabilities** section, check the box that acknowledges **The following resource(s) require capabilities: \[AWS::IAM::Role]**, then click **\[Create stack]**.

The deployment automatically creates the following resources:

- **VPC** (public, EKS-private, and database-private subnets; NAT Gateway; Elastic IP)
- **Amazon EKS cluster** (Kubernetes 1.35, System and User managed node groups, 128 GiB per node)
- **RDS for PostgreSQL** (v16.10, instance class and Multi-AZ as specified in the form, pgvector extension pre-installed)
- **S3 buckets** (private bucket with encryption, versioning, and lifecycle policies; public bucket with CORS)
- **AWS Bedrock Guardrail** (content safety + PII detection, multi-language)
- **AGENTIC STAR application suite** (automatically installed via Helm charts)

> **info**
>
> Deployment time depends on your environment. Monitor progress on the **Events** tab of the CloudFormation console.

> **caution**
>
> If the stack creation fails (for example `ROLLBACK_COMPLETE`), check the reason of the first failed resource in the **Events** tab, fix the cause (such as insufficient vCPU quota), then delete the stack and create it again. Manual recovery of a failed stack is not provided.

## After Deployment

Once the stack reaches `CREATE_COMPLETE`, retrieve the following values from the **Outputs** tab of the CloudFormation console.

| Output Key                | Use                                                                         |
| ------------------------- | --------------------------------------------------------------------------- |
| `EKSClusterName`          | EKS cluster name                                                            |
| `EKSKubectlConfigCommand` | `aws eks update-kubeconfig` command to connect `kubectl` to the EKS cluster |
| `DBInstanceEndpoint`      | RDS endpoint                                                                |
| `S3PublicBucketURL`       | Website URL of the public S3 bucket                                         |

### Configure kubectl

Run the command shown in the `EKSKubectlConfigCommand` output value locally.

```bash
# Example of the command shown in Outputs (use the actual value from your stack)
aws eks update-kubeconfig --region <region> --name <EKSClusterName>
```

Then verify all Pods are `Running`:

```bash
kubectl get pods -A
```

### Checking Access URLs

AGENTIC STAR creates 4 LoadBalancer services (AWS Network Load Balancers) for different purposes.

```bash
kubectl get svc -n ingress-nginx -o wide | grep LoadBalancer
```

| Service Name           | Purpose          | Access URL               |
| ---------------------- | ---------------- | ------------------------ |
| `ingress-nginx-front`  | Main application | `https://<ELB-DNS-NAME>` |
| `ingress-nginx-admin`  | Admin console    | `https://<ELB-DNS-NAME>` |
| `ingress-nginx-extapi` | API endpoint     | `https://<ELB-DNS-NAME>` |

> **note**
>
> The login page (`ingress-nginx-auth`) is intentionally omitted: due to how OAuth redirects work, opening it directly does not produce a working post-login navigation. **Always start from the main application URL** — the login page is invoked automatically when authentication is required.

> **About ELB DNS Names**
>
> Because AWS Network Load Balancers use ENIs spanning multiple Availability Zones, they are assigned a DNS name in the form `xxxxxxxx.elb.<region>.amazonaws.com` (an "ELB DNS name") rather than a fixed IP. AWS may change the underlying IPs over time, so always use the DNS name shown in the `EXTERNAL-IP` column of `kubectl get svc`.

Since self-signed certificates are used, your browser will display certificate warnings. Accept the warning to proceed on first access.

> **tip**
>
> To configure custom domains, point each domain at its LoadBalancer's **ELB DNS name** using a **CNAME** record (A records pointing directly at IPs are not supported on AWS). See the [Domain Settings Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/domain-guide.md) for details.

### Logging In

Open the admin console URL in your browser and log in with the **Administrator Email** and **Administrator Password** you entered in CloudFormation.

As a next step, perform the initial setup in the admin console. See the [Settings Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md) for details.

To start using the API, see the [Marketplace API Quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/quickstart/call-api.md).
