Skip to content

Commit

Permalink
chore: add docs for databases and networking configuration for apps (#62
Browse files Browse the repository at this point in the history
)

## Description

This centralizes documentation for networking configuration and adds
database configuration docs.

## Related Issue

Relates to
defenseunicorns/uds-package-gitlab#124

## Type of change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [X] Other (security config, docs update, etc)

## Checklist before merging

- [X] Test, docs, adr added or updated as needed
- [X] [Contributor Guide
Steps](https://github.com/defenseunicorns/uds-software-factory/blob/main/CONTRIBUTING.md#developer-workflow)
followed
  • Loading branch information
Racer159 authored Jun 12, 2024
1 parent 86de752 commit 8651574
Show file tree
Hide file tree
Showing 5 changed files with 112 additions and 3 deletions.
47 changes: 47 additions & 0 deletions docs/database.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Database

Software Factory applications that require a database are configured to use Postgresql as a backend. This service can be provided to a given application in a few supported ways:

## UDS Postgres Operator Package

If your environment requires an in-cluster solution, you can make use of the [UDS Postgres Operator Package](https://github.com/defenseunicorns/uds-package-postgres-operator). This can be included in your `uds-bundle.yaml` and is configured through the `postgresql` Helm value to create the required CRs for the operator. Below is an example of what this configuration would look like for an application (GitLab in this case):

```yaml
postgresql:
enabled: true
teamId: "uds"
volume:
size: "10Gi"
numberOfInstances: 2
users:
gitlab.gitlab: []
databases:
gitlabdb: gitlab.gitlab
version: "13"
ingress:
- remoteGenerated: Anywhere
```
Within your bundle you are free to make this a `value` or a `variable` override of the `uds-postgres-config` chart within the `postgres-operator` component as desired.

> [!IMPORTANT]
> The above configuration sets the `gitlabdb` to be owned by the `gitlab.gitlab` user which will translate to `{namespace}.{username}` to create a secret that shares the name of the username within the specified namespace. You can learn more about configuring the databases and operator within the [Postgres Operator docs](https://github.com/zalando/postgres-operator/tree/master/docs).

To configure this database within an application you usually will need the secret reference, the username, and the database endpoint. For the above those would be:

- Username: `gitlab.gitlab`
- Secret Reference: `gitlab.gitlab.pg-cluster.credentials.postgresql.acid.zalan.do`
- Database Endpoint: `pg-cluster.postgres.svc.cluster.local`

> [!TIP]
> You can find a practical example of how this is configured within a bundle inside of the `bundles/k3d-demo` bundle where the [Postgres Operator is included](https://github.com/defenseunicorns/uds-software-factory/blob/5c7f9fea76ec074a17555109fc55f733e3d27747/bundles/k3d-demo/uds-bundle.yaml#L39) and where it is [configured to work with applications](https://github.com/defenseunicorns/uds-software-factory/blob/5c7f9fea76ec074a17555109fc55f733e3d27747/bundles/k3d-demo/uds-bundle.yaml#L180).

## External Database Provider (Username/Password)

In order to connect to a database with a username and password you first need to wire up the `postgres.password` key in the UDS config chart to create the required secret reference. Then, depending on your application, will need to wire in the `username`, `endpoint` and any other connection information as the application requires. This is a similar process to the configuration for the Postgres Operator above just providing the values needed for your database service.

## AWS IAM Roles for Service Accounts (IRSA)

Software Factory Packages also support IAM Roles for Service Accounts to connect to the Relational Database Service (RDS). This is done by enabling IRSA on your cluster and creating IAM Roles for Kubernetes Service Accounts to assume. You can see a guide for how to [setup IRSA on EKS within the AWS documentation](https://docs.aws.amazon.com/emr/latest/EMR-on-EKS-DevelopmentGuide/setting-up-enable-IAM.html).

Wiring this into an application is app specific (and will be documented in that app's `configuration.md` file) but generally involves instructing the app to use IAM roles and then annotating the Service Accounts with the correct Amazon Resource Name (ARN) corresponding to the role you want it to assume.
2 changes: 1 addition & 1 deletion docs/development.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Software Factory Development Quickstart
# Development Quickstart

## Apple Silicon Mac Users

Expand Down
62 changes: 62 additions & 0 deletions docs/networking.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Networking

Software Factory applications are configured by default to assume they will connect to the internal dependencies that are used for testing (see examples such as `storage`, `redis` and `postgres` in a given `bundle/uds-bundle.yaml`). This is intentional, so as to not create overly permissive network policies by default. For example, there is not a default setup of egress anywhere for pods that may need to connect to external storage.

> [!IMPORTANT]
> If you are using different internal services, cloud services or a mix you **MUST** configure values in the given config chart accordingly via bundle overrides. A couple of example are provided below.
Configure an application with external services:

```yaml
# charts/config/values.yaml
storage:
internal: false
redis:
internal: false
postgres:
internal: false
```
Configure an application with external postgres and s3, but in-cluster redis:
```yaml
# charts/config/values.yaml
storage:
internal: false
postgres:
internal: false
redis:
internal: true
selector:
app.kubernetes.io/name: redis
namespace: redis
port: 6379
```
> [!TIP]
> There may be a need to integrate with other in-cluster services that are not a part of the standard connectivity needed by the application (as an example a Jira integration with GitLab). As such, Software Factory applications provide the ability to add custom rules to allow additional internal network connectivity.
Add custom rule:
```yaml
# charts/config/values.yaml
custom:
# Notice no `remoteGenerated` field here on custom internal rule
- direction: Ingress
selector:
app: webservice
remoteNamespace: jira
remoteSelector:
app: jira
port: 8180
description: "Ingress from Jira"
# No `remoteNamespace`, `remoteSelector`, or `port` fields on rule to `remoteGenerated`
- direction: Egress
selector:
app: webservice
remoteGenerated: Anywhere
description: "Egress from Webservice"
```
> [!NOTE]
> The above is just an example of what can be done with the custom key and not representative what any specific integration would need to look like.
2 changes: 1 addition & 1 deletion docs/testing.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# SWF Testing
# Testing

Currently we test the UDS Software Factory at two different levels, the overall `bundle`, and the individual `package`. Each level has different tests that it performs in order to save time while still ensuring that the necessary configurations are covered.

Expand Down
2 changes: 1 addition & 1 deletion docs/versioning.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# SWF Versioning
# Versioning

> :warning: **Note:** Packages are the only production release artifacts published from the UDS Software Factory repositories, as bundles are meant to be _created_, not consumed, by users. Repos may publish bundles for demo purposes, but those are not intended for production consumption though will loosely follow standard semantic versioning.
Expand Down

0 comments on commit 8651574

Please sign in to comment.