Skip to content

Add workarounds to remote quickstart #785

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.

Sign up for GitHub

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

Open
augustmckendrick wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add workarounds to remote quickstart #785

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e107f48
Reorganize to add prerequisits to SSH Quickstart
roadnick Apr 29, 2026
6a3e97a
Add workaround to remote quickstart
roadnick May 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 52 additions & 1 deletion docs/quickstarts/quickstart-2-remote.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,58 @@ Note that if you have already done one of the other quickstarts, such as our AWS

Before proceeding, make sure your management cluster meets the following requirements:

1. A [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) is configured on the management cluster to support Persistent Volumes.
1. Increase filesystem limits by adding the following to `/etc/sysctl.conf`:
Copy link
Copy Markdown
Contributor

@eromanova eromanova May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think for now it would be better to document increasing filesystem limits as a known issue with a recommended workaround on a separate page, rather than including it as a prerequisite.


```bash
fs.inotify.max_user_instances=8192
fs.inotify.max_user_watches=524288
```

Then set `systemd` limits:

```bash
sudo tee -a /etc/systemd/system.conf <<EOF
DefaultLimitNOFILE=1048576
EOF

sudo tee -a /etc/systemd/user.conf <<EOF
DefaultLimitNOFILE=1048576
EOF
```

Next set the OS limits:

```bash
sudo tee -a /etc/security/limits.conf <<EOF
* soft nofile 1048576
* hard nofile 1048576
EOF
```

Finally, apply and reboot:

```bash
sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo reboot
```

1. A [default storage class](https://kubernetes.io/docs/tasks/administer-cluster/change-default-storage-class/) is configured on the management cluster to support Persistent Volumes. For example:

```bash
helm repo add openebs https://openebs.github.io/openebs
helm repo update

helm install openebs openebs/openebs \
--namespace openebs \
--create-namespace

kubectl patch storageclass openebs-hostpath \
Comment on lines +56 to +64
Copy link
Copy Markdown
Contributor

@eromanova eromanova May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’ve tested the openebs Helm chart installation using the default configuration from the guide, and it appears that not all components come up successfully (some pods enter a crash loop). In addition, the Helm installation can remain stuck waiting for certain components to become ready. This is likely due to configuration differences, so I think it would be better to avoid being too prescriptive here. Instead of providing direct installation instructions for openebs, it may be clearer to simply reference the official documentation. This would reduce potential confusion for users during setup.

Suggestion: make this step more flexible and less prescriptive. For example:

A Kubernetes storage solution should be deployed on the management cluster, and a default StorageClass should be configured to support PersistentVolumes. One possible option is OpenEBS (see https://openebs.io/docs/quickstart-guide/installation for a quickstart guide).

To set a StorageClass as the default, run:

kubectl patch storageclass <storageClassName>
      -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

-p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'
```

1. Make sure the key you will use to log in as root exists on the child machines.
Copy link
Copy Markdown
Contributor

@eromanova eromanova May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

Suggested change
1. Make sure the key you will use to log in as root exists on the child machines.
1. Make sure that the SSH key you will use to log in as root is properly configured and authorized on all child machines.


2. If the API server will be exposed as a `LoadBalancer`, ensure the appropriate cloud provider is installed on the management cluster.

## Create a Secret object containing the private SSH key to access remote machines
Expand Down