bc_gitops (bc_gitops v0.7.0)
View SourceMain API module for bc_gitops.
bc_gitops is a BEAM-native GitOps reconciler for OTP applications. It monitors a Git repository and automatically deploys, upgrades, or removes applications based on the desired state defined in the repo.
Quick Start
1. Configure the application in your sys.config:
{bc_gitops, [
{repo_url, "https://github.com/myorg/gitops-repo.git"},
{runtime_module, my_app_runtime}
]}
```
2. Implement the `bc_gitops_runtime' behaviour in your runtime module.
3. Start the application:
```
application:start(bc_gitops).Configuration
- repo_url: Git repository URL (required) - local_path: Local clone path (default: /var/lib/bc_gitops) - branch: Git branch to track (default: main) - apps_dir: Directory within repo containing app specs (default: apps) - reconcile_interval: Interval between reconciliations in ms (default: 60000) - runtime_module: Module implementing bc_gitops_runtime behaviour
Summary
Types
action() type is defined in bc_gitops.hrl
Functions
Manually deploy an application.
Get the status of a specific application.
Get the current running state.
Get the desired state (from git repository).
Trigger an immediate reconciliation.
Manually remove an application.
Start the reconciler with the given configuration.
Get the current reconciler status.
Stop the running reconciler.
Alias for reconcile/0.
Manually upgrade an application to a new version.
Types
-type action() :: {deploy, #app_spec{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, source :: #source_spec{type :: release | git | hex | mesh, url :: binary() | undefined, sha256 :: binary() | undefined, ref :: binary() | undefined, mcid :: binary() | undefined}, env :: #{atom() => term()}, health :: #health_spec{type :: http | tcp | custom, port :: pos_integer(), path :: binary() | undefined, interval :: pos_integer(), timeout :: pos_integer(), module :: module() | undefined} | undefined, depends_on :: [atom()], isolation :: isolation_mode(), vm_config :: #vm_config{memory_limit :: pos_integer() | undefined, scheduler_limit :: pos_integer() | undefined, node_prefix :: binary() | undefined, extra_args :: [binary()]} | undefined}} | {remove, #app_state{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, status :: pending | starting | running | stopped | failed | upgrading, path :: file:filename() | undefined, pid :: pid() | undefined, started_at :: calendar:datetime() | undefined, health :: healthy | unhealthy | unknown, env :: #{atom() => term()}, isolation :: isolation_mode(), node :: node() | undefined, os_pid :: pos_integer() | undefined}} | {upgrade, #app_spec{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, source :: #source_spec{type :: release | git | hex | mesh, url :: binary() | undefined, sha256 :: binary() | undefined, ref :: binary() | undefined, mcid :: binary() | undefined}, env :: #{atom() => term()}, health :: #health_spec{type :: http | tcp | custom, port :: pos_integer(), path :: binary() | undefined, interval :: pos_integer(), timeout :: pos_integer(), module :: module() | undefined} | undefined, depends_on :: [atom()], isolation :: isolation_mode(), vm_config :: #vm_config{memory_limit :: pos_integer() | undefined, scheduler_limit :: pos_integer() | undefined, node_prefix :: binary() | undefined, extra_args :: [binary()]} | undefined}, OldVersion :: binary()} | {reconfigure, #app_spec{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, source :: #source_spec{type :: release | git | hex | mesh, url :: binary() | undefined, sha256 :: binary() | undefined, ref :: binary() | undefined, mcid :: binary() | undefined}, env :: #{atom() => term()}, health :: #health_spec{type :: http | tcp | custom, port :: pos_integer(), path :: binary() | undefined, interval :: pos_integer(), timeout :: pos_integer(), module :: module() | undefined} | undefined, depends_on :: [atom()], isolation :: isolation_mode(), vm_config :: #vm_config{memory_limit :: pos_integer() | undefined, scheduler_limit :: pos_integer() | undefined, node_prefix :: binary() | undefined, extra_args :: [binary()]} | undefined}}.
-type app_spec() :: #app_spec{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, source :: #source_spec{type :: release | git | hex | mesh, url :: binary() | undefined, sha256 :: binary() | undefined, ref :: binary() | undefined, mcid :: binary() | undefined}, env :: #{atom() => term()}, health :: #health_spec{type :: http | tcp | custom, port :: pos_integer(), path :: binary() | undefined, interval :: pos_integer(), timeout :: pos_integer(), module :: module() | undefined} | undefined, depends_on :: [atom()], isolation :: isolation_mode(), vm_config :: #vm_config{memory_limit :: pos_integer() | undefined, scheduler_limit :: pos_integer() | undefined, node_prefix :: binary() | undefined, extra_args :: [binary()]} | undefined}.
-type app_state() :: #app_state{name :: atom(), version :: binary(), description :: binary() | undefined, icon :: #icon_spec{type :: url | base64 | identicon, value :: binary() | undefined, mime_type :: binary() | undefined} | undefined, status :: pending | starting | running | stopped | failed | upgrading, path :: file:filename() | undefined, pid :: pid() | undefined, started_at :: calendar:datetime() | undefined, health :: healthy | unhealthy | unknown, env :: #{atom() => term()}, isolation :: isolation_mode(), node :: node() | undefined, os_pid :: pos_integer() | undefined}.
-type health_spec() :: #health_spec{type :: http | tcp | custom, port :: pos_integer(), path :: binary() | undefined, interval :: pos_integer(), timeout :: pos_integer(), module :: module() | undefined}.
action() type is defined in bc_gitops.hrl
-type isolation_mode() :: embedded | vm.
Functions
Manually deploy an application.
This bypasses the git repository and deploys an application directly from the provided spec. The deployment will be overwritten on the next reconciliation if the app is not defined in the git repository.
Get the status of a specific application.
Get the current running state.
Get the desired state (from git repository).
-spec reconcile() -> ok | {error, term()}.
Trigger an immediate reconciliation.
This pulls the latest changes from git and reconciles the current state with the desired state.
Manually remove an application.
This removes an application regardless of the desired state. The application will be redeployed on the next reconciliation if it's defined in the git repository.
Start the reconciler with the given configuration.
This is useful when you want to start the reconciler programmatically instead of through application configuration.
Example
bc_gitops:start_reconciler(#{
repo_url => <<"https://github.com/myorg/gitops.git">>,
runtime_module => my_runtime
}).-spec status() -> {ok, map()} | {error, not_running}.
Get the current reconciler status.
Returns a map containing: - status: Current reconciler status (initializing | ready | synced | degraded | error) - last_commit: SHA of the last processed commit - app_count: Number of managed applications - healthy_count: Number of healthy applications
-spec stop_reconciler() -> ok | {error, term()}.
Stop the running reconciler.
-spec sync() -> ok | {error, term()}.
Alias for reconcile/0.
Manually upgrade an application to a new version.