docs: add dns setup #767
+79
−2
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| --- | ||
| title: DNS Configuration | ||
| type: docs | ||
| weight: 2 | ||
| --- | ||
|
|
||
| UDS Core deploys two Gateways by default - a Tenant Gateway for end-user applications and an Admin Gateway for administrative applications. You can read more about Istio configuration in UDS Core [here](https://uds.defenseunicorns.com/core/configuration/istio/ingress/). This section covers how to configure DNS for these Gateways. | ||
|
|
||
| ### Domain Configuration | ||
| Each Gateway is associated to a wildcard DNS entry that is derived from the `DOMAIN` [variable](https://github.com/defenseunicorns/uds-core/blob/e624d73f79bd6739b6808fbdbf5ca75ebb7c1d3c/src/istio/zarf.yaml#L8) in the UDS Core Istio package. When deploying UDS Core, you can expect two Gateways to be created that match the following domain names: | ||
| - *.<DOMAIN> / Tenant Gateway | ||
| - *.admin.<DOMAIN> / Admin Gateway | ||
|
|
||
| {{% alert-note %}} | ||
| The default value for `DOMAIN` is `uds.dev`, which is intended for development purposes only. For non-development purposes, you should override this value by specifying a value for `domain` in your `uds-config.yaml`. You can find instructions on how to do so [here](https://uds.defenseunicorns.com/core/configuration/istio/ingress/#configure-domain-name-and-tls-for-istio-gateways). | ||
| {{% /alert-note %}} | ||
|
|
||
| ### Bundle Configuration | ||
| {{% alert-note %}} | ||
| UDS Core does not include any cloud provider specific configuration by default. Additional overrides are required to deploy UDS Core on a given provider. This section will refer to AWS, but values can be substituted as needed for other providers. | ||
| {{% /alert-note %}} | ||
|
|
||
| The Admin and Tenant Gateways will be each be bound to an external Load Balancer that is exposed on TCP ports 80 and 443 by default. The Admin Gateway should be configured to use an internal facing Load Balancer and the Tenant Gateway should be configured to use an external facing Load Balancer. Below is an example of overrides that would accomplish this: | ||
| ```yaml | ||
| kind: UDSBundle | ||
| metadata: | ||
| name: core-with-lb-config | ||
| description: A UDS example bundle for deploying UDS Core with external Load Balancer configuration | ||
| version: "0.0.1" | ||
|
|
||
| packages: | ||
| - name: core | ||
| repository: oci://ghcr.io/defenseunicorns/packages/uds/core | ||
| ref: 0.27.0-upstream | ||
|
|
||
| overrides: | ||
| istio-admin-gateway: | ||
| gateway: | ||
| values: | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-type | ||
| value: "external" | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-scheme | ||
| value: "internal" | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-attributes | ||
| value: "load_balancing.cross_zone.enabled=true" | ||
| istio-tenant-gateway: | ||
| gateway: | ||
| values: | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-type | ||
| value: "external" | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-scheme | ||
| value: "internet-facing" | ||
| - path: service.annotations.service\.beta\.kubernetes\.io/aws-load-balancer-attributes | ||
| value: "load_balancing.cross_zone.enabled=true" | ||
| ``` | ||
| {{% alert-note %}} | ||
| These service annotations and their values are subject to change. Please reference documentation from your cloud provider to ensure their validity. | ||
| {{% /alert-note %}} | ||
|
Comment on lines
+56
to
+58
There was a problem hiding this comment. Not sure if this is the right place or necessary, but thoughts on adding a note about static IPs to reduce effects of LBs cycling? Maybe too cloud provider specific though... There was a problem hiding this comment. That's great callout and a good best-practice. I'm not sure if we want to get into cloud-specific deployment best practices in this document though. Unless we disagree that most folks reading this documentation are aware of this behavior, I'm leaning towards keeping this out. There was a problem hiding this comment. Maybe we should just remove this callout altogether, it feels unnecessary the more I think about it. There was a problem hiding this comment. Yeah might be fine to just delete this note - since it's just meant to be an example anyways? |
||
|
|
||
| ### Istio Gateways | ||
| Once UDS Core is deployed, there will be Istio Gateway resources in your cluster. You can find each Gateway in a dedicated namespace: | ||
| ```cli | ||
| $ kubectl get gateway -A | ||
| NAMESPACE NAME AGE | ||
| istio-admin-gateway admin-gateway 1h | ||
| istio-tenant-gateway tenant-gateway 1h | ||
| ``` | ||
|
|
||
| Each Gateway will have a Kubernetes Service of type Load Balancer: | ||
| ```cli | ||
| $ kubectl get svc -A | grep LoadBalancer | ||
| NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE | ||
| istio-admin-gateway admin-ingressgateway LoadBalancer 10.43.82.84 k8s-istioadm-admin...elb.us-east-1.amazonaws.com 15021:30842/TCP,80:31304/TCP,443:31518/TCP 1h | ||
| istio-tenant-gateway tenant-ingressgateway LoadBalancer 10.43.47.182 k8s-istioten-tenant...elb.us-east-1.amazonaws.com 15021:31222/TCP,80:30456/TCP,443:32508/TCP 1h | ||
| ``` | ||
|
|
||
| From here, DNS records can be created for the environment. You can create A records that associate your top-level domain to the Public IP Addresses of your Load Balancers. For subdomains, CNAME records can be used. For more information on how to configure DNS in AWS, see this [documentation](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/routing-to-elb-load-balancer.html). | ||
|
There was a problem hiding this comment.
I think we can leave it if you think it would be valuable, but want to be careful about giving the impression that this only works/has been tested with AWS. Unfortunately I think most docs we could link would be provider specific (i.e. Route53, Cloudflare, ...). Maybe sufficient to just drop the last line and reference "refer to your DNS provider's documentation"? |
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These get clobbered on the docs site preview - could either escape the
<and>characters, or just wrap in code backticks.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oops! how did you render this out?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Using the docs repo, if you have
hugoinstalled locally you can just runhugo serve. You will want to clone or copy core into the./repo-docsfolder first (I use a symlink locally for this), see the script we use to manage this: https://github.com/defenseunicorns/uds-docs/blob/main/scripts/integrated-docs.sh#L22There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would love to better integrate/task-ify this flow: #712