Verrazzano supports three DNS choices for Verrazzano services and applications:
- Free wildcard DNS services (nip.io and sslip.io)
- Oracle Cloud Infrastructure DNS managed by Verrazzano
- Custom (user-managed) DNS
How Verrazzano constructs a DNS domain
Regardless of which DNS management you use, the value in the
spec.environmentName field in your installation will be
prepended to the configured domain in the
section of the custom resource, to form the full DNS domain name used to access Verrazzano endpoints.
For example, if
spec.environmentName is set to
sales and the domain is configured in
Verrazzano will create
sales.us.example.com as the DNS domain for the installation.
Verrazzano can be configured to use either the nip.io or sslip.io free wildcard DNS services. When queried with a hostname with an embedded IP address, wildcard DNS services return that IP address.
For example, using the
nip.io service, the following DNS names all map to the IP address
10.0.0.1.nip.io app.10.0.0.1.nip.io customer1.app.10.0.0.1.nip.io
To configure Verrazzano to use one of these services, set the
field in the Verrazzano custom resource to either
sslip.io; the default is
For example, the following configuration uses
sslip.io, instead of
nip.io, for wildcard DNS with a
dev installation profile:
apiVersion: install.verrazzano.io/v1alpha1 kind: Verrazzano metadata: name: example-verrazzano spec: profile: dev environmentName: default components: dns: wildcard: domain: sslip.io
Verrazzano can directly manage records in Oracle OCI DNS
when configured to use the
spec.components.dns.oci field. This is achieved
through the External DNS Service, which is a component that is
conditionally installed when OCI DNS is configured for DNS management in Verrazzano.
The following prerequisites must be met before using OCI DNS with Verrazzano:
You must have control of a DNS domain.
You must have an OCI DNS Service Zone that is configured to manage records for that domain. Verrazzano also supports the use of both GLOBAL and PRIVATE OCI DNS zones.
A DNS Service Zone is a distinct portion of a domain namespace. You must ensure that the zone is appropriately associated with a parent domain. For example, an appropriate zone name for parent domain
To create an OCI DNS zone using the OCI CLI:
$ oci dns zone create \ -c <compartment ocid> \ --name <zone-name-prefix>.example.com \ --zone-type PRIMARY
To create an OCI DNS zone using the OCI Console, see Managing DNS Service Zones.
You must have a valid OCI API signing key that can be used to communicate with OCI DNS in your tenancy.
For example, you can create an API signing key using the OCI CLI:
$ oci setup keys --key-name myapikey Enter a passphrase for your private key (empty for no passphrase): Public key written to: /Users/jdoe/.oci/myapikey_public.pem Private key written to: /Users/jdoe/.oci/myapikey.pem Public key fingerprint: 39:08:44:69:9f:f5:73:86:7a:46:d8:ad:34:4f:95:29 If you haven't already uploaded your API signing public key through the console, follow the instructions on the page linked below in the section 'How to upload the public key': https://docs.cloud.oracle.com/Content/API/Concepts/apisigningkey.htm#How2
After the key pair has been created, you must upload the public key to your account in your OCI tenancy. For details, see the OCI documentation, Required Keys and OCIDs.
Create an OCI API secret in the target cluster
To communicate with OCI DNS to manage DNS records, Verrazzano needs to be made aware of the necessary API credentials.
A generic Kubernetes secret must be created in the cluster’s
verrazzano-install namespace with the required credentials.
That secret must then be referenced by the custom resource that is used to install Verrazzano.
After you have an OCI API key ready for use, create a YAML file,
oci.yaml, with the API credentials in the form:
auth: region: <oci-region> tenancy: <oci-tenancy-ocid> user: <oci-user-ocid> key: | <oci-api-private-key-file-contents> fingerprint: <oci-api-private-key-fingerprint>
This information typically can be found in your OCI CLI config file or in the OCI Console. The
<oci-api-private-key-file-contents> contents are the PEM-encoded contents of the
key_file value within the OCI CLI
For example, your
oci.yaml file will look similar to the following:
auth: region: us-ashburn-1 tenancy: ocid1.tenancy.oc1..... user: ocid1.user.oc1..... key: | -----BEGIN RSA PRIVATE KEY----- ... -----END RSA PRIVATE KEY----- fingerprint: 12:d3:4c:gh:fd:9e:27:g8:b9:0d:9f:00:22:33:c3:gg
Verrazzano also supports the use of instance principals to communicate with OCI in order to create or update OCI DNS records. Instance principal requires some prerequisites that can be found here.
When using instance principals, your
oci.yaml file will look as follows:
auth: authtype: instance_principal
Then, you can create a generic Kubernetes secret in the cluster’s
verrazzano-install namespace using
$ kubectl create secret generic -n verrazzano-install <secret-name> --from-file=<path-to-oci-yaml-file>
For example, to create a secret named
oci from a file
oci.yaml, do the following:
$ kubectl create secret generic -n verrazzano-install oci --from-file=oci.yaml
This secret will later be referenced from the Verrazzano custom resource used during installation.
Use a Verrazzano helper script to create an OCI secret
Verrazzano also provides a helper script to create the necessary Kubernetes secret based on your OCI CLI config file,
assuming that you have the OCI CLI installed and a valid OCI CLI profile with the required API key information. The script
create_oci_config_secret.sh reads your OCI CLI configuration file to create the secret.
First, download the
$ curl \ -o ./create_oci_config_secret.sh \ https://raw.githubusercontent.com/verrazzano/verrazzano/v1.1.2/platform-operator/scripts/install/create_oci_config_secret.sh
Next, set your
KUBECONFIG environment variable to point to your cluster and run
to display the script options:
$ chmod +x create_oci_config_secret.sh $ export KUBECONFIG=<kubeconfig-file> $ ./create_oci_config_secret.sh -h usage: ./create_oci_config_secret.sh [-o oci_config_file] [-s config_file_section] -o oci_config_file The full path to the OCI configuration file (default ~/.oci/config) -s config_file_section The properties section within the OCI configuration file. Default is DEFAULT -k secret_name The secret name containing the OCI configuration. Default is oci -c context_name The kubectl context to use -a auth_type The auth_type to be used to access OCI. Valid values are user_principal/instance_principal. Default is user_principal. -h Help
For example, to have the script create the YAML file using your
[DEFAULT] OCI CLI profile and then create a Kubernetes secret
oci, you can run the script with no arguments, as follows:
$ ./create_oci_config_secret.sh secret/oci created
The following example creates a secret
myoci using an OCI CLI profile named
$ ./create_oci_config_secret.sh -s dev -k myoci secret/myoci created
When using instance principals all other parameters will be ignored automatically. The following example creates a secret
myoci using OCI instance principal:
$ ./create_oci_config_secret.sh -a instance_principal secret/myoci created
After the OCI API secret is created, create a Verrazzano custom resource for the installation that is configured to use OCI DNS, and reference the secret you created.
As a starting point, download the sample Verrazzano custom resource
install-oci.yaml file for OCI DNS:
$ curl \ -o ./install-oci.yaml \ https://raw.githubusercontent.com/verrazzano/verrazzano/release-1.1/platform-operator/config/samples/install-oci.yaml
install-oci.yaml file to provide values for the following configuration settings in the
custom resource spec:
spec.components.dns.oci.ociConfigSecret should reference the secret created earlier. For details on the
OCI DNS configuration settings, see
For example, a custom resource for a
prod installation profile using OCI DNS might look as follows, yielding
a domain of
myenv.example.com (OCI identifiers redacted):
apiVersion: install.verrazzano.io/v1alpha1 kind: Verrazzano metadata: name: example-verrazzano spec: profile: prod environmentName: myenv components: dns: oci: ociConfigSecret: oci dnsZoneCompartmentOCID: ocid1.compartment.oc1..compartment-ocid dnsZoneOCID: ocid1.dns-zone.oc1..zone-ocid dnsZoneName: example.com
If using a private DNS zone, then the same
prod installation profile using OCI DNS will look as follows:
apiVersion: install.verrazzano.io/v1alpha1 kind: Verrazzano metadata: name: my-verrazzano spec: profile: prod environmentName: myenv components: dns: oci: ociConfigSecret: oci dnsZoneCompartmentOCID: ocid1.compartment.oc1..compartment-ocid dnsZoneOCID: ocid1.dns-zone.oc1..zone-ocid dnsZoneName: example.com dnsScope: PRIVATE
After the custom resource is ready, apply it using
kubectl apply -f <path-to-custom-resource-file>.
You can specify your own externally managed, custom DNS domain. In this scenario, you manage your own DNS domain and all DNS records in that domain.
An externally managed DNS domain is specified in the
field of the Verrazzano custom resource.
When using an externally managed DNS domain, you are responsible for:
- Configuring A records for Verrazzano ingress points (load balancers)
- Configuring CNAME records for hostnames in the domain that point to the A records, as needed
The Verrazzano installer searches the DNS zone you provide for two specific A records.
These are used to configure the cluster and should refer to external addresses of the load balancers provisioned by the user.
The A records need to be created manually.
||Set as the
||Set as the
For example, if
spec.environmentName is set to
example.com, the A records would need to be set up as follows:
198.51.100.10 A ingress-mgmt.myenv.example.com. 203.0.113.10 A ingress-verrazzano.myenv.example.com.
This example assumes that load balancers exist for
198.51.100.10 and for
For a more complete example, see the documentation for setting up Verrazzano on the OLCNE Platform.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.