-
Notifications
You must be signed in to change notification settings - Fork 18
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: add dns setup #767
base: main
Are you sure you want to change the base?
docs: add dns setup #767
Changes from all commits
5cc54c7
e2ac7f9
945a360
74cce19
89a632b
9f622f5
2549261
9529744
6eb191f
9e5405d
567a437
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe we should just remove this callout altogether, it feels unnecessary the more I think about it. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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"? |
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
hugo
installed locally you can just runhugo serve
. You will want to clone or copy core into the./repo-docs
folder 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