Module io.helidon.integrations.oci.sdk.runtime
Package io.helidon.integrations.oci.sdk.runtime

Interface OciConfig

All Superinterfaces:
Prototype.Api
All Known Implementing Classes:
OciConfig.BuilderBase.OciConfigImpl
public interface OciConfig extends Prototype.Api
Configuration used by OciAuthenticationDetailsProvider.

Access the global OciConfig using the OciExtension.ociConfig() method. The configuration for this is delivered via a special "oci.yaml" file. Minimally, this configuration file should have a key named "auth-strategy" or else a list of auth strategies having a key named "auth-strategies". In the later, all of the named auth strategies will be checked in the order they were specified for availability in the runtime environment (see details below). Here is an example for what the configuration would look like when a single auth strategy is explicitly configured : 

     # oci.yaml
     auth-strategy : "config"
And here is another example when the runtime should search true multi auth strategies in order to select the first one available in the runtime environment: 
     # oci.yaml
     # if instance-principals are available then use it, going down the chain checking for availability, etc.
     auth-strategies: "instance-principals, config-file, resource-principal, config"

Each configured OciAuthenticationDetailsProvider.KEY_AUTH_STRATEGY has varying constraints:

  • instance-principals - the JVM must be able to detect that it is running on a OCI compute node instance.
  • resource-principal - the env variable "OCI_RESOURCE_PRINCIPAL_VERSION" is required to be set in the runtime environment.
  • config-file - the $HOME/.oci/config is available on the file system. This configuration also allows for the optional key named config-profile to be used to override the file location in the runtime environment.
  • config - this configuration allows for these additional values to be set: auth-tenant-id, auth-user-id, auth-region, auth-fingerprint, auth-passphrase(), and auth-private-key. Note that this configuration is only recommended in a development (i.e., non-production) environment since it relies on these additional security-sensitive values to be set. Note that these values cannot be sourced out of the Vault since this configuration source is primordial - the vault is not accessible here.
See authStrategies() for additional details.

The default value for OciAuthenticationDetailsProvider.KEY_AUTH_STRATEGY is set to auto, meaning that the authentication strategy will follow a search heuristic to determine the appropriate setting. When running in the OCI runtime environment (i.e., the JVM is running on a detectable OCI compute node instance) then instance-principals is used, with a final fallback set to be config-file (i.e., $HOME/.oci/config).

See Also:

  • Field Details

  • Method Details

    • builder

      static OciConfig.Builder builder()
      Create a new fluent API builder to customize configuration.
      Returns:
      a new builder

    • builder

      static OciConfig.Builder builder(OciConfig instance)
      Create a new fluent API builder from an existing instance.
      Parameters:
      instance - an existing instance used as a base for the builder
      Returns:
      a builder based on an instance

    • create

      static OciConfig create(Config config)
      Create a new instance from configuration.
      Parameters:
      config - used to configure the new instance
      Returns:
      a new instance configured from configuration

    • create

      static OciConfig create()
      Create a new instance with default values.
      Returns:
      a new instance

    • authStrategy

      Optional<String> authStrategy()
      The singular authentication strategy to apply. This will be preferred over authStrategies() if both are present.
      Returns:
      the singular authentication strategy to be applied

    • authStrategies

      List<String> authStrategies()
      The list of authentication strategies that will be attempted by AbstractAuthenticationDetailsProvider when one is called for. This is only used if authStrategy() is not present.
      • auto - if present in the list, or if no value for this property exists.
      • config - the SimpleAuthenticationDetailsProvider will be used, customized with other configuration properties described here.
      • config-file - the ConfigFileAuthenticationDetailsProvider will be used, customized with other configuration properties described here.
      • instance-principals - the InstancePrincipalsAuthenticationDetailsProvider will be used.
      • resource-principal - the ResourcePrincipalAuthenticationDetailsProvider will be used.

      If there are more than one strategy descriptors defined, the first one that is deemed to be available/suitable will be used and all others will be ignored.

      Returns:
      the list of authentication strategies that will be applied, defaulting to auto
      See Also:
      • OciAuthenticationDetailsProvider.AuthStrategy

    • configPath

      Optional<String> configPath()
      The OCI configuration profile path.

      This configuration property has an effect only when config-file is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). When it is present, this property must also be present and then the ConfigFileReader.parse(String) method will be passed this value. It is expected to be passed with a valid OCI configuration file path.

      Returns:
      the OCI configuration profile path

    • configProfile

      Optional<String> configProfile()
      The OCI configuration/auth profile name.

      This configuration property has an effect only when config-file is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as fileConfigIsPresent(). When it is present, this property may also be optionally provided in order to override the default "DEFAULT".

      Returns:
      the optional OCI configuration/auth profile name

    • authFingerprint

      Optional<String> authFingerprint()
      The OCI authentication fingerprint.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the API signing key's fingerprint. See SimpleAuthenticationDetailsProvider.getFingerprint() for more details.

      Returns:
      the OCI authentication fingerprint

    • authKeyFile

      String authKeyFile()
      The OCI authentication key file.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the SimpleAuthenticationDetailsProvider.getPrivateKey(). This file must exist in the user.home directory. Alternatively, this property can be set using either authPrivateKey() or using authPrivateKeyPath().

      Returns:
      the OCI authentication key file

    • authPrivateKeyPath

      Optional<String> authPrivateKeyPath()
      The OCI authentication key file path.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the SimpleAuthenticationDetailsProvider.getPrivateKey(). This file path is an alternative for using authKeyFile() where the file must exist in the user.home directory. Alternatively, this property can be set using authPrivateKey().

      Returns:
      the OCI authentication key file path

    • authPrivateKey

      Optional<char[]> authPrivateKey()
      The OCI authentication private key.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the SimpleAuthenticationDetailsProvider.getPrivateKey(). Alternatively, this property can be set using either authKeyFile() residing in the user.home directory, or using authPrivateKeyPath().

      Returns:
      the OCI authentication private key

    • authPassphrase

      Optional<char[]> authPassphrase()
      The OCI authentication passphrase.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the SimpleAuthenticationDetailsProvider.getPassphraseCharacters().

      Returns:
      the OCI authentication passphrase

    • authRegion

      Optional<String> authRegion()
      The OCI region.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, either this property or RegionProvider must be provide a value in order to set the ConfigFileAuthenticationDetailsProvider.getRegion().

      Returns:
      the OCI region

    • authTenantId

      Optional<String> authTenantId()
      The OCI tenant id.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). This is also known as simpleConfigIsPresent(). When it is present, this property must be provided in order to set the ConfigFileAuthenticationDetailsProvider.getTenantId().

      Returns:
      the OCI tenant id

    • authUserId

      Optional<String> authUserId()
      The OCI user id.

      This configuration property has an effect only when config is, explicitly or implicitly, present in the value for the authStrategies(). When it is present, this property must be provided in order to set the ConfigFileAuthenticationDetailsProvider.getUserId().

      Returns:
      the OCI user id

    • imdsHostName

      String imdsHostName()
      The OCI IMDS hostname.

      This configuration property is used to identify the metadata service url.

      Returns:
      the OCI IMDS hostname

    • imdsTimeout

      Duration imdsTimeout()
      The OCI IMDS connection timeout. This is used to auto-detect availability.

      This configuration property is used when attempting to connect to the metadata service.

      Returns:
      the OCI IMDS connection timeout
      See Also:

    • potentialAuthStrategies

      default List<String> potentialAuthStrategies()
      The list of OciAuthenticationDetailsProvider.AuthStrategy names (excluding OciAuthenticationDetailsProvider.AuthStrategy.AUTO) that are potentially applicable for use. Here, "potentially applicable for use" means that it is set using the authStrategy() attribute on this config bean. If not present then the fall-back looks to use the values explicitly or implicitly set by authStrategies(). Note that the order of this list is important as it pertains to the search/strategy ordering.
      Returns:
      the list of potential auth strategies that are applicable

    • fileConfigIsPresent

      default boolean fileConfigIsPresent()
      Determines whether sufficient configuration is present on this bean to be used for OCI's "file-based" authentication provider. This matches to the OciAuthenticationDetailsProvider.AuthStrategy.CONFIG_FILE.
      Returns:
      true if there is sufficient attributes defined for file-based OCI authentication provider applicability
      See Also:
      • OciAuthenticationDetailsProvider
      • ConfigFileAuthenticationDetailsProvider

    • simpleConfigIsPresent

      default boolean simpleConfigIsPresent()
      Determines whether sufficient configuration is present on this bean to be used for OCI's "simple" authentication provider. This matches to the OciAuthenticationDetailsProvider.AuthStrategy.CONFIG.
      Returns:
      true if there is sufficient attributes defined for simple OCI authentication provider applicability
      See Also:
      • OciAuthenticationDetailsProvider