Creating an Application

Applications define managed runtime settings for hosted deployments, including scaling, managed storage, networking, and authentication. This task explains how to create an application by using the Oracle Cloud Console in the OCI Generative AI service.

On the Applications list page, select Create application. If you need help finding the list page, see Listing Applications.

Basic Information

Enter a name for the application.
Start the name with a letter or underscore, followed by letters, numbers, hyphens, or underscores. The length can be 1 to 255 characters.
(Optional) Enter a description for the application.
Select a compartment to create the application in. The default compartment is the same as the list page, but you can select any compartment that you have permission to work in.

Scaling

For Autoscaling, define how hosted deployments scale to handle load.
- Minimum replicas
  The minimum number of replicas that must always be running. This value must be less than or equal to the maximum replicas value. Default is 1.
- Maximum replicas
  The maximum number of replicas that can run. New replicas are added as load increases, up to this limit. Default is 3 and the maximum is 30. To disable autoscaling, set this value equal to Minimum replicas.
Select a scaling metric.
The service adds replicas when the selected metric exceeds the configured target, up to the maximum replicas value.
- CPU utilization (%)
  Adds replicas when CPU utilization exceeds this percentage, up to the maximum replicas you set. Range: 50–95%.
- Memory utilization (%)
  Adds replicas when memory utilization exceeds this percentage, up to the maximum replicas you set. Range: 50–95%.
- Concurrent requests
  Adds replicas when concurrent requests exceed this value, up to the maximum replicas you set. Range: 1–500.
- Requests per Second (RPS)
  Adds replicas when requests per second exceed the configured target, up to the maximum replicas you set.

Storage (Optional)

If deployments in the application need service-managed storage, you can enable OCI PostgreSQL, OCI Cache, or Oracle Autonomous AI Database.

Enable managed storage for hosted deployments associated with this application. Managed storage is created and managed by the service and is accessible only from the hosted deployment associated with this application. Connection details are provided to the container through environment variables.

If the application needs Managed storage, enable one of the following options.

OCI PostgreSQL
Enable OCI PostgreSQL to provide a managed database for deployments in this application.
For this option:
- Enter the environment variable name that receives the OCI PostgreSQL connection URI. The service adds the connection string to the specified environment variable.
- Storage: Select whether to create storage or use existing storage. If you select existing storage, the application shares the OCI PostgreSQL storage resource with other applications in the tenancy. Each application is assigned a dedicated database, and this application has permission to access only its dedicated database.
OCI Cache
Enable OCI Cache to provide a managed cache for deployments in this application. For this option:
- Enter the environment variable name that receives the OCI Cache connection URI.
- Storage: Select whether to create storage or use existing storage.
Oracle Autonomous Database
Enable Oracle Autonomous AI Database to provide a managed database for deployments in this application. For this option:
- Enter the environment variable name that receives the Autonomous AI Database connection URI.
In addition to the connection string, the service mounts the database user credentials to the following local files in the container:
```
/mnt/secrets/adb/username
/mnt/secrets/adb/password
```

Environment

(Optional) Enter one or more Environment Variables for the deployment as key-value pairs. For each variable, enter the environment variable name and its value. Add as many variables as the application needs.
(Optional) For Vault environment variables, enter the following:
- Variable name
- Vault OCID
- Vault key
- The service adds the vault information to the container as a JSON file. Example JSON code:
```
{
    "vaultId":<vault-ocid>,
    "key":<the secret in the vault>
}
```

Networking (Optional)

Select how deployments in this application route outbound traffic, and how clients access the deployment endpoint.

For Networking, select one of the following options.
- Default (service-managed)
  Allows outbound access to OCI services and the public internet through a service-managed network.
- Custom (customer-managed)
  Routes outbound traffic through a VCN and subnet in the tenancy by using a private endpoint connection. This option is recommended for private, enterprise-integrated deployments. For this option, select the following:
  - VCN compartment
  - VCN
  - Subnet compartment
  - Subnet
  Note
  
  If you select custom networking, all egress traffic is routed to the VCN subnet. If the application also needs internet access, consider using a public subnet and configuring the route table. See Internet Gateway.
Select whether the active deployment for this application is accessed through a public or private endpoint.
- Public
  Accessible from outside the VCN.
- Private
  Accessible only from within the VCN.
  Important
  
  You must use a Generative AI private endpoint. If you don't have one, create a Generative AI private endpoint.
  Select the following information:
  - Private endpoint compartment
  - Private endpoint
After the application is created, you can access it through this private endpoint by using its FQDN or IP address. Example FQDN:
```
https://<pe-name>.pe.inference.generativeai.<region>
.oci.oraclecloud.com/20251112/hostedApplications/{your_application_ocid}
```

Authentication

Select one of the following authentication methods:

Identity domain bearer token: Uses an OAuth access token issued by an OCI IAM identity domain. The token is sent to the target service as a bearer token, and the service validates the token before accepting the request. As a prerequisite, perform the tasks in Setting Up Identity Domain Bearer Token Authentication.
Identity domain browser session: Uses the OAuth 2.1 Authorization Code flow with Proof Key for Code Exchange (PKCE). Browser users are redirected to an OCI identity domain to sign in. The hosted application service obtains an access token on their behalf and establishes a browser session that uses a session cookie.
OCI IAM: Uses OCI IAM request-signature authentication. Each request is cryptographically signed according to OCI API request-signing requirements.

Note

When using the API, use CreateHostedApplication for either identity domain authentication method. In inboundAuthConfig, set inboundAuthConfigType to one of the following values:

IDCS_AUTH_CONFIG: Identity domain bearer token authentication.
IDCS_SESSION_AUTH_CONFIG: Identity domain browser session authentication using the OAuth 2.1 Authorization Code flow with PKCE.

For either type, include idcsConfig with the required domainUrl and scope values. The API schema marks audience as optional. It also defines clientId and clientSecretVaultId as optional fields that apply only to IDCS_SESSION_AUTH_CONFIG. The clientSecretVaultId value is the OCID of an OCI Vault secret containing the OAuth client secret. For details, see InboundAuthConfig and IdcsAuthConfig.

Omitting inboundAuthConfig from an update leaves the application's current authentication configuration unchanged.

To create an application that uses OCI IAM authentication, use CreateHostedApplicationIam with CreateHostedApplicationIamDetails. The OCI IAM API doesn't require an OAuth or IDCS configuration.

Follow the steps for the authentication type that you select. Existing identity domain bearer token and OCI IAM authentication remain supported. After creating an application, you can select Edit on its detail page to change the authentication type.

Identity domain bearer token

For Authentication type, select Identity domain bearer token.
Select one of these options:
- Choose an existing identity domain
  Use the same identity domain in which you created the confidential integrated application in Step 2. Create an Application in the Identity Domain. Select values for the following fields:
  - Identity domain compartment
  - Identity domain
- Paste an identity domain URL
  Example: https://idcs-xxx.identity.oraclecloud.com:443
For Scope, enter the scope configured for the application in the identity domain.

The scope specifies the permissions that the access token grants. Use the scope configured in Step 3. Configure OAuth Settings.
(Optional) For Audience, enter the audience configured for the application in the identity domain.

The audience identifies the service or API that the access token is intended for. To find this value, open the integrated application in the identity domain, select OAuth configuration, and copy Primary audience.
Select Next.

Identity domain browser session

Obtain the identity domain URL, scope, audience, and client ID for the OAuth application configured for the Authorization Code flow with PKCE. Store the OAuth client secret in OCI Vault and record the secret's OCID for the Client secret vault ID field.

For Authentication type, select Identity domain browser session.
Under Type, select one of the following options:
- Choose an existing identity domain: Select the Identity domain compartment and Identity domain for the OAuth application.
- Paste an identity domain URL: Enter the Identity domain URL. For example, https://idcs-xxx.identity.oraclecloud.com:443.
Enter the following values required by the Console for the OAuth application:
- Scope: The scope configured in the identity domain.
- Audience: The audience configured in the identity domain.
- OAuth client ID: The client ID of the OAuth application used for browser sign-in.
- Client secret vault ID: The OCID of the OCI Vault secret containing the OAuth application's client secret.
(Optional) Under Public access path patterns, select Add public path pattern and enter a path that can be accessed without authentication. Repeat for each additional path.

Paths must start with a slash. Examples include /health and /assets/*. Requests to matching paths bypass authentication. Add only paths intended for access without signing in.
Select Next.

OCI IAM

For Authentication type, select OCI IAM.

This option uses OCI IAM request-signature authentication and doesn't require identity domain settings.
Select Next.

Enable Application Logs

Enable resource logging to track application activity, troubleshoot issues, and collect operational insights for hosted deployments.

(Optional) Turn on Enable log.
For Category, select genai-hosted-deployment-log or create a new log group.
For Log group, select an existing log group or select Create new log group.
Select the compartment that contains the log group.
Enter a log name.
(Optional) Under Advanced options, select a log retention period.
The default retention period is 1 month (30 days).

Review and Create

Review the application settings, then select Create application.

Note

Application creation time depends on the resources that the service provisions for the application.

If managed storage is enabled, the service provisions a dedicated storage instance, which might take several minutes.
If custom networking is selected, the service provisions the required network bridging resources, which might also take several minutes.

Review the settings and select Create application.

Tip

After you create an application, you can view its details and perform other tasks, such as moving it to a different compartment, managing its tags, or deleting it. Use the Actions menu (three dots) in the Console to access these tasks. You can also create a deployment for the application from its detail page. For more information, see Listing Applications.

Oracle Cloud Infrastructure Documentation