kubernetes
/
git-sync
mirror of https://github.com/kubernetes/git-sync.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README and other docs

This commit is contained in:
Tim Hockin 2023-04-07 10:35:39 -07:00
parent e15c7a9695
commit 8ee0f7ef9a
6 changed files with 69 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
README.md
View File

@ -6,21 +6,24 @@ use the [v3.x branch](https://github.com/kubernetes/git-sync/tree/release-3.x).
# git-sync # git-sync
git-sync is a simple command that pulls a git repository into a local directory. git-sync is a simple command that pulls a git repository into a local
It is a perfect "sidecar" container in Kubernetes - it can periodically pull directory, waits for a while, then repeats. As the remote repository chan ges,
files down from a repository so that an application can consume them. those changes will be synced locally. It is a perfect "sidecar" container in
Kubernetes - it can pull files down from a repository so that an application
can consume them.
git-sync can pull one time, or on a regular interval. It can pull from the git-sync can pull one time, or on a regular interval. It can pull from the
HEAD of a branch, from a git tag, or from a specific git hash. It will only HEAD of a branch, from a git tag, or from a specific git hash. It will only
re-pull if the target of the run has changed in the upstream repository. When re-pull if the referenced target has changed in the upstream repository (e.g. a
it re-pulls, it updates the destination directory atomically. In order to do new commit on a branch). It "publishes" each sync through a worktree and a
this, it uses a git worktree in a subdirectory of the `--root` and flips a named symlink. This ensures an atomic update - consumers will not see a
symlink. partially constructed view of the local repository.
git-sync can pull over HTTP(S) (with authentication or not) or SSH. git-sync can pull over HTTP(S) (with authentication or not) or SSH.
git-sync can also be configured to make a webhook call upon successful git repo git-sync can also be configured to make a webhook call or exec a command upon
synchronization. The call is made after the symlink is updated. successful git repo synchronization. The call is made after the symlink is
updated.
## Major update: v3.x -> v4.x ## Major update: v3.x -> v4.x
@ -75,23 +78,36 @@ docker run -d \
nginx nginx
``` ```
### Flags
git-sync has many flags and optional features (see the manual below). Most of
those flags can be configured through environment variables, but in most cases
(with the obvious exception of passwords) flags are preferred, because the
program can abort if an invalid flag is specified, but a misspelled environment
variable will just be ignored. We've tried to stay backwards-compatible across
major versions (by accepting deprecated flags and environment variables), but
some things have evolved, and users are encouraged to use the most recent flags
for their major verion.
### Volumes ### Volumes
The `--root` flag must indicate either a directory that either a) does not The `--root` flag must indicate either a directory that either a) does not
exist (it will be created); or b) exists and is empty; or c) can be emptied by exist (it will be created); or b) exists and is empty; or c) can be emptied by
removing all of the contents. removing all of the contents.
Why? Git demands to clone into an empty directory. If the directory exists Why? Git really wants an empty directory, to avoid any confusion. If the
and is not empty, git-sync will try to empty it by removing everything in it directory exists and is not empty, git-sync will try to empty it by removing
(we can't just `rm -rf` the dir because it might be a mounted volume). If that everything in it (we can't just `rm -rf` the dir because it might be a mounted
fails, git-sync will abort. volume). If that fails, git-sync will abort.
With the above example or with a Kubernetes `emptyDir`, there is usually no With the above example or with a Kubernetes `emptyDir`, there is usually no
problem. The problematic case is when the volume is the root of a filesystem, problem. The problematic case is when the volume is the root of a filesystem,
which sometimes contains metadata (e.g. ext{2,3,4} have a `lost+found` dir). which sometimes contains metadata (e.g. ext{2,3,4} have a `lost+found` dir).
Git will not clone into such a directory (`fatal: destination path The only real solution is to use a sub-directory of the volume as the `--root`.
'/tmp/git-data' already exists and is not an empty directory`). The only real
solution is to use a sub-directory of the volume as the `--root`. ## More docs
More documentation on specific topics can be [found here](./docs).
## Manual ## Manual
@ -102,7 +118,7 @@ NAME
git-sync - sync a remote git repository git-sync - sync a remote git repository
SYNOPSIS SYNOPSIS
git-sync --repo=<repo> [OPTION]... git-sync --repo=<repo> --root=<path> [OPTIONS]...
DESCRIPTION DESCRIPTION
@ -128,7 +144,8 @@ DESCRIPTION
OPTIONS OPTIONS
Many options can be specified as either a commandline flag or an environment Many options can be specified as either a commandline flag or an environment
variable. variable, but flags are preferred because a misspelled flag is a fatal
error while a misspelled environment variable is silently ignored.
--add-user, $GITSYNC_ADD_USER --add-user, $GITSYNC_ADD_USER
Add a record to /etc/passwd for the current UID/GID. This is Add a record to /etc/passwd for the current UID/GID. This is
@ -140,9 +157,6 @@ OPTIONS
(200) and produce a series of key=value lines, including (200) and produce a series of key=value lines, including
"username=<value>" and "password=<value>". "username=<value>" and "password=<value>".
--change-permissions <int>, $GITSYNC_PERMISSIONS
Change permissions on the checked-out files to the specified mode.
--cookie-file <string>, $GITSYNC_COOKIE_FILE --cookie-file <string>, $GITSYNC_COOKIE_FILE
Use a git cookiefile (/etc/git-secret/cookie_file) for Use a git cookiefile (/etc/git-secret/cookie_file) for
authentication. authentication.
@ -165,8 +179,8 @@ OPTIONS
--exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND --exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND
An optional command to be executed after syncing a new hash of the An optional command to be executed after syncing a new hash of the
remote repository. This command does not take any arguments and remote repository. This command does not take any arguments and
executes with the synced repo as its working directory. The executes with the synced repo as its working directory. The following
environment variable $GITSYNC_HASH will be set to the git hash that environment variables $GITSYNC_HASH will be set to the git hash that
was synced. The execution is subject to the overall --sync-timeout was synced. The execution is subject to the overall --sync-timeout
flag and will extend the effective period between sync attempts. flag and will extend the effective period between sync attempts.
This flag obsoletes --sync-hook-command, but if sync-hook-command This flag obsoletes --sync-hook-command, but if sync-hook-command
@ -211,6 +225,13 @@ OPTIONS
- off: Disable explicit git garbage collection, which may be a good - off: Disable explicit git garbage collection, which may be a good
fit when also using --one-time. fit when also using --one-time.
--group-write, $GITSYNC_GROUP_WRITE
Ensure that data written to disk (including the git repo metadata,
checked out files, worktrees, and symlink) are all group writable.
This corresponds to git's notion of a "shared repository". This is
useful in cases where data produced by git-sync is used by a
different UID. This replaces the older --change-permissions flag.
-h, --help -h, --help
Print help text and exit. Print help text and exit.

9
cmd/git-sync/main.go
View File

@ -2245,7 +2245,7 @@ NAME
git-sync - sync a remote git repository git-sync - sync a remote git repository
SYNOPSIS SYNOPSIS
git-sync --repo=<repo> [OPTION]... git-sync --repo=<repo> --root=<path> [OPTIONS]...
DESCRIPTION DESCRIPTION
@ -2271,7 +2271,8 @@ DESCRIPTION
OPTIONS OPTIONS
Many options can be specified as either a commandline flag or an environment Many options can be specified as either a commandline flag or an environment
variable. variable, but flags are preferred because a misspelled flag is a fatal
error while a misspelled environment variable is silently ignored.
--add-user, $GITSYNC_ADD_USER --add-user, $GITSYNC_ADD_USER
Add a record to /etc/passwd for the current UID/GID. This is Add a record to /etc/passwd for the current UID/GID. This is
@ -2305,8 +2306,8 @@ OPTIONS
--exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND --exechook-command <string>, $GITSYNC_EXECHOOK_COMMAND
An optional command to be executed after syncing a new hash of the An optional command to be executed after syncing a new hash of the
remote repository. This command does not take any arguments and remote repository. This command does not take any arguments and
executes with the synced repo as its working directory. The following executes with the synced repo as its working directory. The
environment variables $GITSYNC_HASH will be set to the git hash that $GITSYNC_HASH environment variable will be set to the git hash that
was synced. The execution is subject to the overall --sync-timeout was synced. The execution is subject to the overall --sync-timeout
flag and will extend the effective period between sync attempts. flag and will extend the effective period between sync attempts.
This flag obsoletes --sync-hook-command, but if sync-hook-command This flag obsoletes --sync-hook-command, but if sync-hook-command

8
docs/askpass-url.md
View File

@ -1,4 +1,4 @@
# Using an Http Auth URL with git-sync # Using an HTTP auth URL with git-sync
## Step 1: Create a GIT_ASKPASS HTTP Service ## Step 1: Create a GIT_ASKPASS HTTP Service
@ -8,15 +8,15 @@ Example of the service's output, see more at <https://git-scm.com/docs/gitcreden
``` ```
username=xxx@example.com username=xxx@example.com
password=ya29.mysecret password=mysecret
``` ```
## Step 2: Configure git-sync container ## Step 2: Configure git-sync container
In your git-sync container configuration, specify the GIT_ASKPASS URL In your git-sync container configuration, specify the GIT_ASKPASS URL
The credentials will pass in plain text, make sure the connection between git-sync The credentials will pass in plain text, so make sure the connection between
and GIT ASKPASS Service are secure. git-sync and GIT ASKPASS Service is secure.
See the askpass e2e test as an example. See the askpass e2e test as an example.

17
docs/cookie-file.md
View File

@ -1,10 +1,10 @@
# Using an Http Cookie File with git-sync # Using an HTTP cookie file with git-sync
Git-sync supports use of an HTTP Cookie File for accessing git content. Git-sync supports use of an HTTP cookie file for accessing git content.
## Step 1: Create Secret ## Step 1: Create a Secret
First, create a secret file from the git cookie file you wish to First, create a Kubernetes Secret from the git cookie file you wish to
use. use.
Example: if the cookie-file is `~/.gitcookies`: Example: if the cookie-file is `~/.gitcookies`:
@ -16,9 +16,9 @@ kubectl create secret generic git-cookie-file --from-file=cookie_file=~/.gitcook
Note that the key is `cookie_file`. This is the filename that git-sync will look Note that the key is `cookie_file`. This is the filename that git-sync will look
for. for.
## Step 2: Configure Pod/Deployment Volume ## Step 2: Configure a Pod/Deployment volume
In your Pod or Deployment configuration, specify a Volume for mounting the In your Pod or Deployment configuration, specify a volume for mounting the
cookie-file Secret. Make sure to set `secretName` to the same name you used to cookie-file Secret. Make sure to set `secretName` to the same name you used to
create the secret (`git-cookie-file` in the example above). create the secret (`git-cookie-file` in the example above).
@ -30,13 +30,12 @@ volumes:
defaultMode: 0440 defaultMode: 0440
``` ```
## Step 3: Configure git-sync container ## Step 3: Configure a git-sync container
In your git-sync container configuration, mount your volume at In your git-sync container configuration, mount your volume at
"/etc/git-secret". Make sure to pass the `--cookie-file` flag or set the "/etc/git-secret". Make sure to pass the `--cookie-file` flag or set the
environment variable `GITSYNC_COOKIE_FILE` to "true", and to use a git repo environment variable `GITSYNC_COOKIE_FILE` to "true", and to use a git repo
(`--repo` flag or `GITSYNC_REPO` env) is set to use a URL with the HTTP (`--repo` or `GITSYNC_REPO`) with an HTTP URL.
protocol.
```yaml ```yaml
name: "git-sync" name: "git-sync"

4
docs/proxy.md
View File

@ -10,7 +10,7 @@ Lastly, [see similar issue for FluxCD](https://github.com/fluxcd/flux/pull/3152)
## Step 1: Create configuration ## Step 1: Create configuration
Create a ConfigMap to store your configuration: Create a Kubernetes ConfigMap to store your configuration:
```bash ```bash
cat << EOF >> /tmp/ssh-config cat << EOF >> /tmp/ssh-config
@ -45,4 +45,4 @@ spec:
- name: ssh-config - name: ssh-config
configMap: configMap:
name: ssh-config name: ssh-config
``` ```

6
v3-to-v4.md
View File

@ -127,6 +127,12 @@ specify `--depth=0`.
The logging output for v3 was semi-free-form text. Log output in v4 is The logging output for v3 was semi-free-form text. Log output in v4 is
structured and rendered as strict JSON. structured and rendered as strict JSON.
## Root dir
git-sync v3 container images defaulted `--root` to "/tmp/git". In v4, that has
moved to "/git". Users who mount a volume and expect to use the default
`--root` must mount it on "/git".
## Other changes ## Other changes
git-sync v3 would allow invalidly formatted env vars (e.g. a value that was git-sync v3 would allow invalidly formatted env vars (e.g. a value that was