Skip to content

Commit

Permalink
Cleaned up troubleshooting and security documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@seriva
seriva committed Oct 24, 2019
1 parent 4c2ec45 commit fd5225f
Show file tree
Hide file tree
Showing 3 changed files with 7 additions and 179 deletions.
10 changes: 2 additions & 8 deletions docs/home/HOWTO.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,14 +44,8 @@
- [How to upgrade Kafka cluster](./howto/UPGRADE.md#how-to-upgrade-Kafka-cluster)

- [Security](./howto/SECURITY.md)
- Epicli
- [How to use TLS/SSL certificate with HA Proxy](./howto/SECURITY.md#how-to-use-tls/ssl-certificate-with-ha-proxy)
- [How to enable AWS disk encryption](./howto/SECURITY.md#how-to-enable-AWS-disk-encryption)
- Legacy
- [How to use TLS/SSL certificate with HA Proxy in a legacy cluster](./howto/SECURITY.md#how-to-use-tls/ssl-certificate-with-ha-proxy-in-a-legacy-cluster)
- [How to enable or disable network traffic - firewall](./howto/SECURITY.md#how-to-enable-or-disable-network-traffic)
- [Client certificate for Azure VPN connection](./howto/SECURITY.md#client-certificate-for-azure-vpn-connection)
- [How to set HA Proxy load balancer to minimize risk of Slowloris like attacks](./howto/SECURITY.md#how-to-set-HA-Proxy-load-balancer-to-minimize-risk-of-Slowloris-like-attacks)
- [How to use TLS/SSL certificate with HA Proxy](./howto/SECURITY.md#how-to-use-tls/ssl-certificate-with-ha-proxy)
- [How to enable AWS disk encryption](./howto/SECURITY.md#how-to-enable-AWS-disk-encryption)
- [How to use Kubernetes Secrets](./howto/SECURITY.md#how-to-use-kubernetes-secrets)
- [How to authenticate to Azure AD app](./howto/SECURITY.md#how-to-authenticate-to-azure-ad-app)

Expand Down
33 changes: 0 additions & 33 deletions docs/home/TROUBLESHOOTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,38 +1,5 @@
# Troubleshooting

## Epicli

TODO

## Legacy

### Service Principal

When you first launch Epiphany on Azure you will be prompted to register your device. This process generates a token that is used to create an Azure Service Principal. At times, Azure can not fully propagate fast enough so you may see an error that resembles something like below:

```text
====> Login using service principal...
Get Token request returned http error: 400 and server response: {"error":"unauthorized_client","error_description":"AADSTS70001: Application with identifier '1c38cb1b-7cbe-4bf5-8d17-bee51d5d6502' was not found in the directory 372ee9e0-9ce0-4033-a64a-c07073a91ecd
Trace ID: fe4358f1-7250-4ad9-b6ce-c7da80101700
Correlation ID: 441a5caf-66d8-4252-a783-c0abcf60c40e
Timestamp: 2018-07-18 08:30:12Z","error_codes":[70001],"timestamp":"2018-07-18 08:30:12Z","trace_id":"fe4358f1-7250-4ad9-b6ce-c7da80101700","correlation_id":"441a5caf-66d8-4252-a783-c0abcf60c40e"}
```

Simply re-launch the command line and the Service Principal should be propagated. Repeat if necessary. This is not very common but has been seen.

### Terraform

The Terraform backend feature along with Azure Service Principal is the default configuration. This allows for multiple team members to modify the IaaS (VM) services on Azure. This works as expected from most networks. However, we have seen an error generated by Terraform on certain networks. This can be resolved simply by setting two options in the `data.yaml` file for your given environment. These are as follows:

```yaml
# Comments excluded here for clarity
terraform:
service_principal:
enable: false
backend:
enable: false
```
## Kubernetes

Sometimes Google has a connection issue with pulling down images. You may see something like below:
Expand Down
143 changes: 5 additions & 138 deletions docs/home/howto/SECURITY.md
View file
Original file line number Diff line number Diff line change
@@ -1,18 +1,17 @@
## Epicli

### How to use TLS/SSL certificate with HA Proxy
## How to use TLS/SSL certificate with HA Proxy

TODO

### How to enable AWS disk encryption
## How to enable AWS disk encryption

#### EC2 Root volumes
### EC2 Root volumes

Since [May 2019](https://aws.amazon.com/about-aws/whats-new/2019/05/launch-encrypted-ebs-backed-ec2-instances-from-unencrypted-amis-in-a-single-step/) AWS supports the creation of instances from unencrypted AMIs. At this point Terraform does not [support](https://github.com/terraform-providers/terraform-provider-aws/issues/8624) this jet. If you need encrypted root volumes for now you need to supply your own pre-encryped AMIs as specified in the guide [here](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIEncryption.html).

We will add this as the functionality becomes available in Terraform. The issue is beeing tracked [here](https://github.com/epiphany-platform/epiphany/issues/381).

#### Additional EC2 storage
### Additional EC2 storage

When defining extra storage inside the `infrastructure/virtual-machine` document one can set the `encryption` flag:

Expand All @@ -27,142 +26,10 @@ additional_disks:
...
```

#### EFS storage
### EFS storage

EFS storage is encrypted by default.

## Legacy

### How to use TLS/SSL certificate with HA Proxy in a legacy cluster

If you want to use HAProxy with TLS/SSL certificate follow the instruction below.

1. Add haproxy_tls_termination role to your data.yaml
2. If you want to use your certificates, you can add to section core to your data.yaml:

```yaml
haproxy:
haproxy_certs_dir: your_path_to_certificates
```
Your certificates will be copied and applied automatically to HA Proxy configuration.
Please be aware that `your_path_to_certificates` cannot contain variables (`$HOME`) or tilde (`~`) as this will make deployment of Epiphany fail. Additionally if you need more than one DNS name for your frontend you need to provide certificates on your own, as there is only one self-signed certificate generated by this role with CN localhost. For multiple backends you need to provide also mapping as described in later part of this document.

3. If you don't want to apply your certificates that will be generated automatically, then just don't put any certificate in `your_path_to_certificates` or don't put section with `haproxy: haproxy_certs_dir` in your data.yaml

4. Below you can find example of configuration:
```yaml
haproxy:
haproxy_certs_dir: /home/epiphany/certs/
frontend:
- name: https_front
port: 443
https: yes
backend:
- http_back1
- http_back2
domain_backend_mapping:
- domain: backend1.domain.com
backend: http_back1
- domain: backend2.domain.com
backend: http_back2
- name: http_front1
port: 80
https: no
backend:
- http_back2
- name: http_front2
port: 8080
https: no
backend:
- http_back1
- http_back2
domain_backend_mapping:
- domain: http-backend1.domain.com
backend: http_back1
- domain: http-backend2.domain.com
backend: http_back2
backend:
- name: http_back1
server_groups:
- worker
port: 30001
- name: http_back2
server_groups:
- worker
- kibana
port: 30002
```

5. Parameters description:

`haproxy_certs_dir` - (Optional) Path on machine from which you run Epiphany installer where certificates generated by you are stored. If not one certificate with CN localhost will be generated, works only with one frontend definition, in other cases it won't be able to redirect you to correct backend on HAProxy.

`frontend` - (Mandatory) At least one frontend configuration must exist, if more than one domain must be supported than `domain_backend_mapping` section is mandatory, as this will make fail. This is a list of frontend, each position has to start with `-`.

- `name` - (Mandatory) Name of each configuration for frontend.
- `port` - (Mandatory) Port to which frontend should be binding. Must be unique for all frontends in other case it will make HAProxy fail.
- `https` - (Mandatory) Information if https will be used - options `yes`/`no`. If `no`, only http part of configuration for frontend will be generated.
- `backend` - (Mandatory) At least one backend configuration must exist. If `domain_backend_mapping` exists this must match configuration in `domain_backend_mapping` backend section. It always has to match configuration from backend name section. This is a list of backend, each position has to start with `-`. This parameter shows to which backend configuration forward traffic from frontend to backend.

- `domain_backend_mapping` - (Optional) If this exist at least one domain to backend mapping must exist. Must be provided if more than one domain has to be supported.

- `domain` - (Mandatory if `domain_backend_mapping` used for each mapping) Domain that matches SSL certificate CN for https configuration and domain name. For http, domain that will be mapped using http header.
- `backend` - (Mandatory if `domain_backend_mapping` used for each mapping) Must match name from backend section

`backend` - (Mandatory) This is a list of backend, each position has to start with `-`. At least one backend used by frontend must exist. If there won't be a match with each frontend configuration HAProxy will fail to start.
- `name` - (Mandatory) Name of each configuration for backend, must match frontend backend configuration and `domain_backend_mapping` backend part in frontend section.
- `server_groups` - (Mandatory) This is a list of server groups, each position has to start with `-`. At least one `server_group` used by backend must exist. It must match Epiphany role e.g. `kibana`, `worker` etc.
- `port` - (Mandatory) Port on which backend service is exposed.

### How to enable or disable network traffic

#### VM Firewall

Epiphany 1.0 supports firewalld on host machines (RedHat only). You can enable firewall setting `.../security/firewall/enable` to `true` in data.yaml. Remember to allow port 22 to be open in ports_open (`.../security/firewall/ports_open`) dictionary in order to configuration can do its job.

#### Azure specific - Network Security Group

Security for internet facing infrastructure is extremely important thing - remember to configure `Network Security Group` rules to allow network traffic only on required ports and directions. You can do it using Azure specific data.yaml in section `.../network_security_group/rules`. Remember to allow port 22 (you can/should remove this rule after deployment) in order to configuration can do its job.

### Client certificate for Azure VPN connection

Epiphany will create point to site configuration (if you enable VPN in `.../security/vpn/enable` and specify public key of your certificate, in base64 format, in `public_cert_data` field). For production environments you have to use root certificate from `trusted provider`.
For development purposes you can use self signed certificate which can be generated using powershell: <https://docs.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-certificates-point-to-site>

When you get root certificate you should generate child certificate(s) that will be distributed to the team that should have VPN access to clusters.
Configuration of client config in data.yaml (`.../security/vpn/client_configuration/root_certificate`) looks like following:

```yaml
...
root_certificate:
# name is the name of the cert that was created for you by a trusted party OR a name you give a self-signed cert
name: NAME-OF-YOUR-CERTIFICATE
revoked_certificate:
name: NAME-OF-REVOKED-CERTIFICATE
thumbprint: THUMBPRINT-OF-REVOKED-CERTIFICATE
# public_cert_data is the actual base64 public key from your cert. Put it in 'as is'. The '|' tells yaml to use 'as is'.
public_cert_data: |
YOUR-BASE64-CLIENT-AUTH-PUBLIC-KEY
...
```

### How to set HA Proxy load balancer to minimize risk of Slowloris like attacks

1. Add haproxy_tls_termination role to your data.yaml
2. If you want to minimize risk of Slowloris like attacks add to your data.yaml in section for haproxy:

```yaml
haproxy:
http_request_timeout: 5s
```

Where http_request_timeout is the number_of_seconds with s after which connection to HAProxy will be terminated by HAProxy.
This parameter is optional, if is not present no timeout http-request in global section of HAProxy configuration will be set.

Configuration requires to have revoked certificate filled in (for now).

## How to use Kubernetes Secrets

Prerequisites: Epiphany Kubernetes cluster
Expand Down

0 comments on commit fd5225f

Please sign in to comment.