From 33410b770d3793bef3449c8a3e7d48eb2b5716ea Mon Sep 17 00:00:00 2001 From: Yanks Yoon <37652070+yanksyoon@users.noreply.github.com> Date: Mon, 22 Jan 2024 18:40:10 +0800 Subject: [PATCH] docs: ssh debug integration docs (#195) * feat: initial ssh-debug integration * fix: linting and test fixes * test: add debug info tests * fix: relation data & tests * test: fix unit test * feat: flush runners on relation changed * fix: lint * test: validate SHA fingerprint format * fix: flush only idle runners * fix: remove remote unit filter * fix: use underscore for env vars * test: tmate action test * test: tmate action test * test: add ssh_debug test to workflow * test: rename relation * fix: json serializable state * fix: optional state serialization * fix: use machine address * fix: test branch naming * docs: ssh-debug integration docs * docs: add docstring to testing option values * docs: integration test workflow value comment * docs: update master to main * docs: improve wording * docs: parser help messages * Update tests/conftest.py Co-authored-by: Christopher Bartz --------- Co-authored-by: Christopher Bartz --- .github/workflows/integration_test.yaml | 2 + docs/explanation/ssh-debug.md | 12 ++++++ docs/how-to/debug-with-ssh.md | 53 +++++++++++++++++++++++++ docs/reference/integrations.md | 11 +++++ tests/conftest.py | 40 +++++++++++++++---- tests/integration/conftest.py | 15 +++++-- 6 files changed, 122 insertions(+), 11 deletions(-) create mode 100644 docs/explanation/ssh-debug.md create mode 100644 docs/how-to/debug-with-ssh.md create mode 100644 docs/reference/integrations.md diff --git a/.github/workflows/integration_test.yaml b/.github/workflows/integration_test.yaml index b6bdea75a..115b62a33 100644 --- a/.github/workflows/integration_test.yaml +++ b/.github/workflows/integration_test.yaml @@ -4,6 +4,8 @@ on: pull_request: jobs: + # test option values defined at test/conftest.py are passed on via repository secret + # INTEGRATION_TEST_ARGS to operator-workflows automatically. integration-tests-juju2: name: Integration test with juju 2.9 uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main diff --git a/docs/explanation/ssh-debug.md b/docs/explanation/ssh-debug.md new file mode 100644 index 000000000..568465cfc --- /dev/null +++ b/docs/explanation/ssh-debug.md @@ -0,0 +1,12 @@ +# SSH Debug + +SSH debugging allows a user to identify and resolve issues or errors that occur through the secure +shell (SSH) connection between a client and a server. + +To enhance the security of the runner and the infrastructure behind the runner, only user ssh-keys +registered on [Authorized Keys](https://github.com/tmate-io/tmate-ssh-server/pull/93) are allowed +by default on [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server/). + +Authorized keys are registered via [action-tmate](https://github.com/canonical/action-tmate/)'s +`limit-access-to-actor` feature. This feature uses GitHub users's SSH key to launch an instance +of tmate session with `-a` option, which adds the user's SSH key to `~/.ssh/authorized_keys`. diff --git a/docs/how-to/debug-with-ssh.md b/docs/how-to/debug-with-ssh.md new file mode 100644 index 000000000..03b2be427 --- /dev/null +++ b/docs/how-to/debug-with-ssh.md @@ -0,0 +1,53 @@ +# How to debug with ssh + +The charm exposes an integration `debug-ssh` interface which can be used with +[tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server/) to pre-configure runners with +environment variables to be picked up by [action-tmate](https://github.com/canonical/action-tmate/) +for automatic configuration. + +## Prerequisites + +To enhance the security of self-hosted runners and its infrastracture, only authorized connections +can be established. Hence, action-tmate users must have +[ssh-key registered](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) +on the GitHub account. + +## Deploying + +Use the following command to deploy and integrate github-runner with tmate-ssh-server. + +```shell +juju deploy tmate-ssh-server +juju integrate tmate-ssh-server github-runner +``` + +Idle runners will be flushed and restarted. Busy runners will be configured automatically on next +spawn. + +## Using the action + +Create a workflow that looks like the following within your workflow to enable action-tmate. + +```yaml +name: SSH Debug workflow example + +on: [pull_request] + +jobs: + build: + runs-on: [self-hosted] + steps: + - uses: actions/checkout@v3 + - name: Setup tmate session + uses: canonical/action-tmate@main +``` + +The output of the action looks like the following. + +``` + +SSH: ssh -p 10022 @ +or: ssh -i -p10022 @ +``` + +Read more about [action-tmate's usage here](https://github.com/canonical/action-tmate). diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md new file mode 100644 index 000000000..123e0b3e0 --- /dev/null +++ b/docs/reference/integrations.md @@ -0,0 +1,11 @@ +# Integrations + +### debug-ssh + +_Interface_: debug-ssh +_Supported charms_: [tmate-ssh-server](https://charmhub.io/tmate-ssh-server) + +Debug-ssh integration provides necessary information for runners to provide ssh reverse-proxy +applications to setup inside the runner. + +Example debug-ssh integrate command: `juju integrate github-runner tmate-ssh-server` diff --git a/tests/conftest.py b/tests/conftest.py index 0369bf288..c36b583a0 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -9,11 +9,35 @@ def pytest_addoption(parser: Parser): """Add options to pytest parser.""" - parser.addoption("--path", action="store") - parser.addoption("--token", action="store") - parser.addoption("--charm-file", action="store") - parser.addoption("--token-alt", action="store") - parser.addoption("--http-proxy", action="store") - parser.addoption("--https-proxy", action="store") - parser.addoption("--no-proxy", action="store") - parser.addoption("--loop-device", action="store") + parser.addoption( + "--path", + action="store", + help="The path to repository in / or / format.", + ) + parser.addoption("--token", action="store", help="The GitHub Personal Access Token.") + parser.addoption( + "--charm-file", action="store", help="The prebuilt github-runner-operator charm file." + ) + parser.addoption( + "--token-alt", action="store", help="An alternative token to test the change of a token." + ) + parser.addoption( + "--http-proxy", + action="store", + help="HTTP proxy configuration value for juju model proxy configuration.", + ) + parser.addoption( + "--https-proxy", + action="store", + help="HTTPS proxy configuration value for juju model proxy configuration.", + ) + parser.addoption( + "--no-proxy", + action="store", + help="No proxy configuration value for juju model proxy configuration.", + ) + parser.addoption( + "--loop-device", + action="store", + help="The loop device to create shared FS for metrics logging", + ) diff --git a/tests/integration/conftest.py b/tests/integration/conftest.py index d5204d4dd..8a8664805 100644 --- a/tests/integration/conftest.py +++ b/tests/integration/conftest.py @@ -86,7 +86,10 @@ def charm_file(pytestconfig: pytest.Config, loop_device: Optional[str]) -> str: def path(pytestconfig: pytest.Config) -> str: """Configured path setting.""" path = pytestconfig.getoption("--path") - assert path, "Please specify the --path command line option" + assert path, ( + "Please specify the --path command line option with repository " + "path of / or / format." + ) return path @@ -94,7 +97,10 @@ def path(pytestconfig: pytest.Config) -> str: def token(pytestconfig: pytest.Config) -> str: """Configured token setting.""" token = pytestconfig.getoption("--token") - assert token, "Please specify the --token command line option" + assert token, ( + "Please specify the --token command line option with GitHub Personal Access " + "Token value." + ) return token @@ -102,7 +108,10 @@ def token(pytestconfig: pytest.Config) -> str: def token_alt(pytestconfig: pytest.Config, token: str) -> str: """Configured token_alt setting.""" token_alt = pytestconfig.getoption("--token-alt") - assert token_alt, "Please specify the --token-alt command line option" + assert token_alt, ( + "Please specify the --token-alt command line option with GitHub Personal " + "Access Token value." + ) assert token_alt != token, "Please specify a different token for --token-alt" return token_alt