Oracle Cloud Infrastructure Documentation

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

  1. 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.
  2. (Optional) Enter a description for the application.
  3. 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.

Tags

  1. (Optional) Select Add tag and assign tags to this application. See Resource Tags.
  2. Select Create.

Scaling

Important

If you plan to enable persistent file storage in step 3, set Minimum replicas and Maximum replicas to 1. Persistent file storage supports one replica in this release.
  1. 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.

  2. 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

In step 3, enable the service-managed storage that deployments in the application need: File Storage, OCI PostgreSQL, OCI Cache, or Oracle Autonomous AI Database. You can attach one storage resource of each type.

File Storage is available at a container mount path. Database and cache connection details are provided through environment variables. The service manages access to the application's storage.

In Storage, turn on the options that your application needs.
  • Persistent file storage

    Retain files across container restarts and redeployments. Each application can have one file storage attachment with a fixed 50 GB quota (50,000,000,000 bytes).

    For this option:

    1. Turn on Persistent file storage.
    2. Ensure that Minimum replicas and Maximum replicas in the scaling settings are both 1. Persistent file storage supports one replica in this release.
    3. Under Storage, select one of the following:
      • Create a new storage: Enter a Storage name. The service creates a storage configuration in the application's compartment.
      • Select an existing storage in the current compartment: Under Storage name, select one active file storage resource. You can use Search and Filter to find a resource. If no active file storage is available, select Create a new storage.
    4. For Mount path, keep /mnt/persistent/data or enter another valid absolute container path. You can't change this path after the application is created.

    Applications that use the same storage resource receive separate file systems. Selecting existing storage reuses its configuration. It doesn't share another application's files.

    Configure your application to read and write persistent files at the mount path. File Storage doesn't use an environment variable for connection information. For path requirements, API configuration, and attachment status, see Persistent File Storage for Hosted Applications.

  • 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

  1. (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.
  2. (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.

  1. 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.
  2. 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

In step 6, select one of the following authentication options:

  • 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.
  • No authentication: Allows requests without platform-managed authentication. Use this option for public content or when your application manages authentication.
Note

When using the API, use CreateHostedApplication for identity domain authentication or no authentication. 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.
  • NO_AUTH_CONFIG: Disables platform-managed caller authentication. Omit idcsConfig.

For either identity domain authentication 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.

To configure no authentication, supply the following object. No separate tenancy enrollment is required.

"inboundAuthConfig": {
  "inboundAuthConfigType": "NO_AUTH_CONFIG"
}

Omitting inboundAuthConfig from an update leaves the application's current authentication configuration unchanged. To explicitly disable platform-managed caller authentication, set inboundAuthConfigType to NO_AUTH_CONFIG and omit idcsConfig.

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.

Identity domain bearer token

  1. For Authentication type, select Identity domain bearer token.
  2. 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

  3. 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.

  4. (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.

  5. 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.

  1. For Authentication type, select Identity domain browser session.
  2. 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.
  3. 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.
  4. (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.

  5. Select Next.

OCI IAM

  1. For Authentication type, select OCI IAM.

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

  2. Select Next.

No authentication

With this option, anyone who can reach the endpoint can send requests without platform-managed authentication. If access needs restriction, your application must enforce authentication and authorization. See Using No Authentication.

  1. For Authentication type, select No authentication.
    No additional authentication fields are required.
  2. Select Next.

Enable Application Logs

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

  1. (Optional) Turn on Enable log.
  2. For Category, select genai-hosted-deployment-log or create a new log group.
  3. For Log group, select an existing log group or select Create new log group.
  4. Select the compartment that contains the log group.
  5. Enter a log name.
  6. (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 or attaches the selected storage, 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.
If you selected No authentication, verify that Authentication type shows that value.

After creation, view Authentication type under Authentication on the application's Configuration tab.

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.