|
| 1 | +--- |
| 2 | +applies_to: |
| 3 | + deployment: |
| 4 | + self: |
| 5 | + ece: |
| 6 | + eck: |
| 7 | +navigation_title: Configure Elastic agent with custom certificate |
| 8 | +products: |
| 9 | + - id: cloud-kubernetes |
| 10 | + - id: cloud-enterprise |
| 11 | +--- |
| 12 | + |
| 13 | +# Configure AutoOps {{agent}} with a custom SSL certificate |
| 14 | + |
| 15 | +{{agent}} might not recognize your SSL certificate if it is signed by a custom or internal Certificate Authority (CA). In this case, {{agent}} will fail to connect your self-managed cluster to AutoOps and you might encounter an error like the following: |
| 16 | + |
| 17 | +```sh |
| 18 | +... x509: certificate signed by unknown authority ... |
| 19 | +``` |
| 20 | + |
| 21 | +This error occurs because the machine where you have installed {{agent}} does not trust your custom or internal CA. To fix this error, follow the steps on this page to configure the agent with your custom SSL certificate. |
| 22 | + |
| 23 | +## Add custom certificate path to the `elastic-agent.yml` file |
| 24 | + |
| 25 | +To configure {{agent}} with your custom SSL certificate, add the path to your certificate to the [`elastic-agent.yml`](/reference/fleet/configure-standalone-elastic-agents.md) policy file on the host machine where the agent is installed. |
| 26 | + |
| 27 | +Complete the following steps: |
| 28 | + |
| 29 | +1. On the host machine, open the `elastic-agent.yml` file. The default location is `/opt/Elastic/Agent/elastic-agent.yml`. |
| 30 | +2. In the `elastic-agent.yml` file, locate the `receivers.metricbeatreceiver.metricbeat.modules` section. |
| 31 | +3. In this section, there are two modules configured for `autoops_es`, one for metrics and one for templates. \ |
| 32 | + Add the `ss.certificate_authorities` setting to both these modules using one of the following options: |
| 33 | + |
| 34 | + :::::{tab-set} |
| 35 | + :group: add-cert-auth-setting-to-module |
| 36 | + |
| 37 | + ::::{tab-item} Use environment variable (recommended) |
| 38 | + :sync: env-variable |
| 39 | + |
| 40 | + We recommend using this method because it's flexible and keeps sensitive paths out of your main configuration. |
| 41 | + |
| 42 | + Add the following line to both `autoops_es` modules: |
| 43 | + |
| 44 | + ```yaml |
| 45 | + ssl.certificate_authorities: |
| 46 | + - ${env:AUTOOPS_CA_CERT} |
| 47 | + ``` |
| 48 | + After adding this line to both modules, make sure the` AUTOOPS_CA_CERT` environment variable is set on the host machine and contains the full path to your certificate file (for example: `/etc/ssl/certs/my_internal_ca.crt`). |
| 49 | + :::: |
| 50 | + |
| 51 | + ::::{tab-item} Hardcode file path |
| 52 | + :sync: hardcode-file-path |
| 53 | + |
| 54 | + Use this method to specify the path directly. This method is often simpler for fixed or test environments. |
| 55 | + |
| 56 | + Edit the following line with the path to your CA and add it to both `autoops_es` modules: |
| 57 | + |
| 58 | + ```yaml |
| 59 | + ssl.certificate_authorities: |
| 60 | + - "/path/to/your/ca.crt" |
| 61 | + ``` |
| 62 | + The following codeblock shows what your final configuration should look like when you use the hardcode method. |
| 63 | + |
| 64 | + ```yaml |
| 65 | + receivers: |
| 66 | + metricbeatreceiver: |
| 67 | + metricbeat: |
| 68 | + modules: |
| 69 | + # Metrics |
| 70 | + - module: autoops_es |
| 71 | + hosts: ${env:AUTOOPS_ES_URL} |
| 72 | + period: 10s |
| 73 | + metricsets: |
| 74 | + - cat_shards |
| 75 | + - cluster_health |
| 76 | + - cluster_settings |
| 77 | + - license |
| 78 | + - node_stats |
| 79 | + - tasks_management |
| 80 | + # --- ADD THIS LINE --- |
| 81 | + ssl.certificate_authorities: |
| 82 | + - "/path/to/your/ca.crt" |
| 83 | + |
| 84 | + # Templates |
| 85 | + - module: autoops_es |
| 86 | + hosts: ${env:AUTOOPS_ES_URL} |
| 87 | + period: 24h |
| 88 | + metricsets: |
| 89 | + - cat_template |
| 90 | + - component_template |
| 91 | + - index_template |
| 92 | + # --- ADD THIS LINE --- |
| 93 | + ssl.certificate_authorities: |
| 94 | + - "/path/to/your/ca.crt" |
| 95 | + ``` |
| 96 | + |
| 97 | + :::: |
| 98 | + |
| 99 | + ::::: |
| 100 | + |
| 101 | +4. Save your changes to the `elastic-agent.yml` file. |
| 102 | +5. Restart {{agent}} so that the new settings can take effect.\ |
| 103 | + In most systemd-based Linux environments, you can use the following command to restart the agent: |
| 104 | + ```bash |
| 105 | + sudo systemctl restart elastic-agent |
| 106 | + ``` |
| 107 | +6. Check the agent logs again to confirm that the error is gone and that {{agent}} has successfully connected your self-managed cluster to AutoOps. |
| 108 | + |
| 109 | + :::{note} |
| 110 | + If you encounter the following error in the agent logs, there might be a formatting issue in the `elastic-agent.yml` file. |
| 111 | + ```sh |
| 112 | + ... can not convert 'object' into 'string' ... ssl.certificate_authorities ... |
| 113 | + ``` |
| 114 | + To fix this error, ensure your configuration is correctly formatted. The `ss.certificate_authorities` setting must be a list item (indicated by the `-`) containing one or more strings (the respective path to your certification files). |
| 115 | + ::: |
0 commit comments