diff --git a/Using-Oracle-Cloud-Infrastructure-DNS.md b/Using-Oracle-Cloud-Infrastructure-DNS.md new file mode 100644 index 0000000..9296d63 --- /dev/null +++ b/Using-Oracle-Cloud-Infrastructure-DNS.md @@ -0,0 +1,76 @@ +# Using Oracle Cloud Infrastructure DNS + +The Oracle Cloud Infrastructure (OCI) DNS service lets you +[create and manage public and private DNS zones][DNS] in an OCI tenancy. +The DNS Service provides each tenancy with a limit of 1,000 zones and 25,000 +records per zone and is [charged per 1M queries][COST]. + +Before you can use OCI DNS with `acme.sh`, you'll need the following: + +* A private [API signing key][APIKEY]; and +* The [tenancy and service account OCIDs][OCIDS] + +We recommend [installing the OCI CLI][CLI] and using the [interactive setup process][CSTP] +to create an API signing keypair. + +Alternatively, the [OCI Developer Guide][DG] provides the manual steps required +to generate the API signing keys and determine the required OCIDs. + +## Configuring the `dns_oci` plugin + +To use the `dns_oci` plugin, the following environment variables must be +configured: + +* `OCI_CLI_USER`: OCID of the user calling the API. Example: `ocid1.user.oc1..` +* `OCI_CLI_TENANCY`: OCID of your tenancy. Example: `ocid1.tenancy.oc1..` +* `OCI_CLI_REGION`: Your Oracle Cloud Infrastructure home region. + +You also need to provide the API signing key using one of the +following two variables: + +* `OCI_CLI_KEY_FILE`: Path to the file containing the private API signing key + in PEM format; or +* `OCI_CLI_KEY`: the private API signing key in PEM format + +### Issuing a certificate + +To issue a certificate, ensure either the OCI CLI is working correctly or all +the mandatory environment variables have been configured, then run: + +```shell +acme.sh --issue --dns dns_oci -d example.com -d www.example.com +``` + +To issue a wildcard certificate, use:: + +```shell +acme.sh --issue --dns dns_oci -d example.com -d *.example.com +``` + +## Security recommendations + +The **[Oracle Cloud Infrastructure Security Guide][OSG]** details the recommended +**[best practices for securing user authentication][BP]** which include: + +* creating **a dedicated service user account** specifically for GitHub Actions; +* assigning that service account a **unique** and **complex** password; +* **rotating the API signing key pair** used by the service account every 90 days; and +* using **[GitHub encrypted secrets][GHS]** to store credentials. + +## Reporting an issue + +Please use to report +any issues or bugs. + +[DNS]: https://docs.oracle.com/en-us/iaas/Content/DNS/Tasks/managingdnszones.htm#Managing_DNS_Service_Zones +[COST]: https://www.oracle.com/cloud/price-list.html#dns +[DG]: https://docs.oracle.com/en-us/iaas/Content/API/Concepts/devtoolslanding.htm +[APIKEY]: https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm +[OCIDS]: https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#five +[CLI]: https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm +[CSTP]:https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm#configfile +[OSG]: https://docs.oracle.com/en-us/iaas/Content/Security/Concepts/security_guide.htm +[BP]: https://docs.oracle.com/en-us/iaas/Content/Security/Reference/iam_security.htm +[GHS]: https://docs.github.com/en/actions/reference/encrypted-secrets +[REGS]: https://docs.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm#top +[CLIVARS]: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clienvironmentvariables.htm