oxidecomputer / oxidecomputer/packer-plugin-oxide

Improve oxide-instance builder documentation

Open
#83 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Packer Plugin Task
Dominant language
Go
Stars
2
Forks
1
Avg merge
3h 9m
Merged PRs (30d)
3

Description

Summary

Several areas of the oxide-instance builder documentation are missing or underdeveloped. This issue tracks the documentation improvements needed to make the plugin more approachable and production-ready for users.

Items

Authentication guidance
Document the security tradeoffs between inline host/token fields versus environment variables (OXIDE_HOST, OXIDE_TOKEN). Inline credentials risk being committed to version control; env vars are preferred for CI/CD pipelines. Add guidance on token scoping and rotation.

Cleanup behavior on failure
Explicitly document what resources are and are not cleaned up when a build fails. Users need to know whether a failed build can leave behind a running instance, an orphaned disk, or a partial image — and if so, how to find and clean up those resources.

Timeout defaults
Document the current hardcoded timeout values for instance boot, SSH readiness, and image creation. Even if these are not yet user-configurable, knowing the defaults helps users understand why a build is hanging and set expectations for long-running provisioners.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No documentation file or test is named. Start by locating the oxide-instance builder documentation and the implementation of authentication, failure cleanup, and timeout handling. Done means the docs explain credential choices and token practices, resource cleanup after failures, and the current boot, SSH-readiness, and image-creation timeout defaults.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
devops, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.