Administration Service The deployment control plane for Extract and Replicat in Oracle GoldenGate Microservices, and the place where many successful builds either become orderly or quietly brittle.
Administration Service is where operators create processes, wire them to database aliases, inspect checkpoints, read reports, attach managed profiles, and prove whether a deployment is healthy for local capture and apply. It is also the place where confusion starts if you treat Service Manager, Administration Service, Distribution Service, and Receiver Service as interchangeable.
Administration Service is the deployment control plane, not the whole microservices estate
The cleanest way to understand Administration Service is to treat it as the command and observation layer for replication processes that live inside one deployment. It supervises, administers, manages, and monitors Extract and Replicat, along with the local configuration objects those processes depend on. That makes it central, but not universal.
Operators often over-ascribe responsibility to it because the web interface feels like the product. In practice, the microservices estate is split across several services with different boundaries. If you blur those lines, you get common errors: attempting to diagnose missing trail movement from the wrong page, assuming a Replicat can run before a path has landed a trail, or expecting host-level security changes to appear automatically inside every deployment.
Administration Service creates and manages local Extract and Replicat processes, parameter files, credential-store aliases, checkpoint and heartbeat objects, and automation tasks. It does not replace Service Manager host control, and it does not replace Distribution Service or Receiver Service for network path creation and trail landing.
What it is
The surface you use to add, alter, start, stop, inspect, and troubleshoot Extract and Replicat inside a deployment.
What it is not
Not the host watchdog, not the cross-deployment inventory system, and not the dedicated routing interface for distribution paths.
Why the distinction matters
A process can be perfectly defined in Administration Service and still be non-functional because the prerequisite database state or the route that should land its trail lives elsewhere.
Its place in the architecture is easiest to see when you separate host control, local process control, and transport
Microservices becomes easier to operate when each service is treated as a distinct operational surface. Service Manager owns host-level deployment lifecycle. Administration Service owns process lifecycle inside a deployment. Distribution Service and Receiver Service own movement and landing of trails across deployment boundaries.
| Need | Use this surface | Why | Frequent mistake |
|---|---|---|---|
| Start or stop a whole deployment | Service Manager | Deployment lifecycle is a host concern, not a local Extract or Replicat concern. | Looking for deployment restart controls inside Administration Service. |
| Create or alter Extract and Replicat | Administration Service | It owns process definitions, process status, parameter text, checkpoint state, and reports. | Treating Distribution Service as a full process-creation surface. |
| Create the route that lands a remote trail | Distribution Service and Receiver Service | Transport and landing are a separate problem from local process creation. | Building Replicat first and assuming a trail will appear later. |
| Confirm whether the problem is local process health or route health | Start in Administration Service, then branch to Distribution or Receiver as needed | A green process state proves only part of the pipeline. | Stopping diagnosis when Extract or Replicat merely says RUNNING. |
Service Manager answers, “Is this deployment alive and reachable?” Administration Service answers, “Are my local capture and apply objects correctly defined and behaving?” Distribution and Receiver answer, “Did the trail move and land where I intended?”
The same control plane is exposed through browser, Admin Client, and REST, but they are not interchangeable in practice
Administration Service is fronted by three access styles. They all target the same service logic, but they serve different operational purposes. Good teams pick the surface that best matches the task instead of treating one interface as universally superior.
Browser UI
Best for guided creation and fast visual review of current process state, checkpoints, parameters, and reports. No separate client installation is required.
Admin Client
Best for repeatable operations, scripted runbooks, and precise command history. It uses the same service-side logic through documented commands.
REST
Best for external orchestration when a platform team wraps GoldenGate in a wider automation layer. The service interface is foundational, not incidental.
Do not confuse these two credential stores
ADD CREDENTIALSin Admin Client stores deployment login material in a wallet local to the client machine and user account.ALTER CREDENTIALSTOREcreates database aliases inside the GoldenGate deployment so Extract and Replicat can useUSERIDALIAS.- Deployment login credentials are not the same thing as database aliases.
Secure connection details that matter
- For secure deployments using certificate files, Admin Client needs
OGG_CLIENT_TLS_CAPATHto trust the server certificate chain. - If the server uses a self-signed certificate, Admin Client can connect with the
!override onCONNECTwhile that certificate remains valid. - IDP-enabled deployments use an access token on
CONNECTinstead of the ordinary username and password flow.
export PATH=$OGG_HOME/bin:$PATH export OGG_CLIENT_TLS_CAPATH=/ogg/certs/rootca.pem adminclient ADD CREDENTIALS sm_ops USER svc_admin PASSWORD "<deployment_password>" CONNECT <service_manager_uri> DEPLOYMENT ggmetro AS sm_ops
Most Administration Service failures are really prerequisite failures that show up late
The service can only control what has been prepared correctly. That means database grants, registration, supplemental logging, checkpoint strategy, and route state must be considered before you click or type your way into process creation. Otherwise the UI simply becomes the place where the failure becomes visible.
Deployment-side prerequisites
- Service Manager and the target deployment must already exist and be reachable.
- Your login role must match the action. User is read-only, Operator is operational, Administrator can alter non-security objects, and Security can manage security objects.
- If the deployment was added under an existing Service Manager, only the original administrator account spans all deployments by default; later-created users are deployment-specific.
- If you will use Admin Client from another host, the client trust material has to match the deployment security model.
Database-side prerequisites
- Create the database credential aliases before process creation so the flow can bind to
USERIDALIAS. - Enable the right supplemental logging model before Extract starts. Table-level
TRANDATAor schema-level logging is not optional. - For Oracle integrated Extract, connect with
DBLOGIN USERIDALIAS, then register the Extract before creating the integrated Extract group. - Create a checkpoint table before an ordinary integrated Replicat.
- If the Replicat is in a different deployment from the Extract, confirm the target-side trail has already landed there.
Do not blindly reuse older Administration Server examples that add version-specific parameters without checking modern behavior. One common trap is copying NOSCHEDULINGCOLS into Oracle 21c and higher environments where auto-capture capabilities make that guidance outdated for many cases.
Source signal
If REGISTER EXTRACT or ADD TRANDATA is the failing step, the problem is usually database privilege, container context, or logging setup, not the UI itself.
Target signal
If Replicat creation succeeds but startup fails immediately, inspect checkpoint-table and target-alias assumptions before changing process parameters.
Route signal
If both local processes look well-defined but data still does not move, verify the landing trail and path state before touching local process definitions.
What Administration Service actually owns day to day is broader than process creation
Serious GoldenGate operations use Administration Service for more than the initial add-process wizard. The long-term value is that it centralizes the state that keeps a deployment recoverable and understandable.
Process lifecycle
Add, alter, delete, register, unregister, start, stop, restart, and inspect Extract and Replicat groups. This includes status, lag, statistics, checkpoints, parameter files, and reports.
Database control objects
Create and inspect checkpoint tables, heartbeat tables, trace tables, credential-store aliases, and supplemental logging state for schema and table objects.
Managed behavior
Attach profiles for autostart and autorestart, mark critical processes, and shape how process recovery behaves after interruption or abend.
Operational automation
Configure recurring tasks such as purge trails, purge process, archive trails, and lag reporting that used to live in more fragmented classic-era patterns.
Administration Service becomes more valuable after cutover than during installation. If you only think of it as the page where you initially add an Extract and a Replicat, you miss the surfaces that make restarts, lag reviews, cleanup, and post-incident diagnosis manageable.
The safest operator flow is connect, define identity, prepare databases, create processes, then validate each layer separately
The order matters. If you reverse it, the service lets you create objects that look fine but are not yet operational. The following sequence assumes a modern Microservices deployment where the source-side Extract and the target-side Replicat are each managed from Administration Service, and where any cross-deployment trail transport is handled separately.
Connect to the deployment through Service Manager or directly to Administration Service as the correct role-scoped user.
Create source and target database aliases in the deployment credential store.
Use DBLOGIN to prepare source logging and Extract registration in the right database context.
Create Extract, local trail, and parameter text in the source deployment.
Create checkpoint objects, then create Replicat in the target deployment after the trail lands.
Start processes, inspect lag and reports, and attach profiles/tasks only after the base flow is proven.
adminclient
CONNECT <service_manager_uri> DEPLOYMENT ggmetro AS svc_admin
INFO ALL
-- If the deployment health itself is in doubt:
HEALTH DEPLOYMENT ggmetro
ALTER CREDENTIALSTORE ADD USER c##gg_admin@cdbnorth ALIAS src_fin DOMAIN OracleGoldenGate ALTER CREDENTIALSTORE ADD USER c##gg_admin@cdbsouth ALIAS tgt_fin DOMAIN OracleGoldenGate INFO CREDENTIALSTORE DOMAIN OracleGoldenGate
For multitenant Oracle databases with different users or services for CDB and PDB access, the alias must reflect the correct connection context. If your Extract registration or TRANDATA work needs a specific PDB, make sure the alias and the connected container agree before you proceed.
DBLOGIN USERIDALIAS src_fin DOMAIN OracleGoldenGate ADD TRANDATA PDBFIN.fin.orders ADD TRANDATA PDBFIN.fin.invoice_lines REGISTER EXTRACT ecapinv DATABASE CONTAINER (PDBFIN) ADD EXTRACT ecapinv, INTEGRATED TRANLOG, BEGIN NOW ADD EXTTRAIL lt, EXTRACT ecapinv, MEGABYTES 256
EXTRACT ecapinv USERIDALIAS src_fin DOMAIN OracleGoldenGate EXTTRAIL lt LOGALLSUPCOLS UPDATERECORDFORMAT COMPACT TABLE fin.orders; TABLE fin.invoice_lines;
DBLOGIN USERIDALIAS tgt_fin DOMAIN OracleGoldenGate
ADD CHECKPOINTTABLE ogg_admin.ckpt_fin
ADD HEARTBEATTABLE
-- Use the target-side trail name that already lands in this deployment.
ADD REPLICAT rinv1, INTEGRATED, EXTTRAIL lt, CHECKPOINTTABLE ogg_admin.ckpt_fin
REPLICAT rinv1 USERIDALIAS tgt_fin DOMAIN OracleGoldenGate MAP fin.orders, TARGET fin_rpt.orders; MAP fin.invoice_lines, TARGET fin_rpt.invoice_lines;
START EXTRACT ecapinv START REPLICAT rinv1
Once the processes are proven, attach the appropriate managed profile or managed-process settings for autostart, autorestart, and critical-process behavior from the deployment controls. Do that after correctness is established, not before.
Verification should prove service reachability, database state, process state, and readable diagnostics
A solid Administration Service check does not stop at a green badge. You need to verify that the deployment control plane is reachable, the aliases and database objects are valid, the processes are advancing, and the service can show you usable diagnostic evidence when something is wrong.
INFO ALL INFO CREDENTIALSTORE DOMAIN OracleGoldenGate INFO TRANDATA PDBFIN.fin.orders INFO TRANDATA PDBFIN.fin.invoice_lines INFO CHECKPOINTTABLE ogg_admin.ckpt_fin STATUS EXTRACT ecapinv STATUS REPLICAT rinv1 LAG EXTRACT ecapinv LAG REPLICAT rinv1 STATS EXTRACT ecapinv, TOTAL STATS REPLICAT rinv1, TOTAL VIEW PARAMS ecapinv VIEW PARAMS rinv1 VIEW REPORT ecapinv VIEW REPORT rinv1
| Check | Command or view | What a healthy signal looks like | What it proves |
|---|---|---|---|
| Deployment control plane | INFO ALL |
The service surfaces respond and show the expected process inventory. | You are connected to the right deployment and the control plane itself is alive. |
| Alias inventory | INFO CREDENTIALSTORE DOMAIN OracleGoldenGate |
The aliases you expect exist in the correct domain. | The process definitions are not depending on invisible or mistyped database identities. |
| Source readiness | INFO TRANDATA |
Supplemental logging shows for the intended tables. | The database will provide the change detail that downstream processing needs. |
| Replicat recovery safety | INFO CHECKPOINTTABLE |
The checkpoint table is visible in the correct schema and database context. | Replicat restart behavior has a durable recovery anchor. |
| Operational motion | STATUS, LAG, STATS |
Processes are not only running, they are advancing sensibly for the real workload. | The service can expose runtime activity rather than only static configuration. |
| Readable evidence | VIEW PARAMS, VIEW REPORT |
The service returns current parameter text and report content without ambiguity. | You have the two artifacts you need most when a process definition is operationally wrong. |
When to use the report first
If a process starts and immediately stops or abends, go to the report before touching the parameter file. Connection failures, mapping errors, registration issues, and trail-position problems usually become obvious there much faster than from status alone.
When to use parameter text first
If the process runs but behavior is unexpected, verify the actual parameter text being used. Old assumptions survive most often in copied MAP, trail, alias, and catalog statements, not in the status page.
The most common Administration Service incidents come from boundary confusion, alias confusion, and order-of-operations mistakes
None of the following failure patterns are exotic. They are what happen when a service-oriented interface hides the fact that several layers still have to agree: login scope, deployment scope, database scope, trail scope, and process scope.
| Symptom | Likely cause | What to inspect first | Next action |
|---|---|---|---|
| Reach SM but cannot perform Admin Service action | Wrong role or wrong deployment scope. | User role, deployment selection, and user's original scope. | Reconnect to intended deployment and confirm role limits. |
| Extract add fails at registration | Database grants, alias context, or multitenant scope are wrong. | DBLOGIN context, grant model, and PDB prerequisites. |
Fix the database side first, then repeat registration. |
| Replicat definition succeeds but startup fails immediately | Checkpoint table, target alias, or target trail assumptions are wrong. | INFO CHECKPOINTTABLE, alias resolution, trail presence. |
Correct the target dependency before adjusting mappings. |
| Everything looks green but target data is stale | The route is broken, or process is idle on an empty trail. | Trail landing, Distribution/Receiver state, Replicat report. | Branch into transport diagnosis. This is a route problem. |
| Admin Client cannot connect to the secure deployment | Client trust material is missing, invalid, or mismatched. | OGG_CLIENT_TLS_CAPATH, cert validity, access token use. |
Fix trust and connection method. Do not assume service is down. |
| Old examples fail on modern DB releases | Copied parameters are version-stale. | Check for deprecated logging options and process-mode assumptions. | Reduce config to current documented minimums, then expand. |
Do not start by editing process parameters unless you know which layer failed. First decide whether the issue is service reachability, user role scope, database prerequisite state, trail landing, or runtime process behavior.
Version-aware notes that change how an expert should read Administration Service examples
The core role of the service has been stable since the early Microservices releases, but a few details matter when you move between older training material and current operational estates.
Server vs Service terminology
Older material commonly says Administration Server. Current docs use both Administration Service and Server. The operational role is the same.
Security flow is broader now
Current deployments use certificate-based trust and external identity providers. Admin Client connecting via access token is a modern pattern.
Password & alias behavior
Modern releases support much longer passwords for GoldenGate credentials and continue to separate Admin Client credentials from DB aliases.
Logging examples need review
Legacy logging guidance shouldn't be copied into Oracle 21c/23ai environments. Auto-capture makes older supplemental-logging options outdated.
Administration Service is the place where Oracle GoldenGate Microservices becomes operable at the deployment level. It gives you a disciplined control plane for local Extract and Replicat lifecycle, database aliases, checkpointing, process diagnostics, and recurring operational tasks.
The right posture is simple: keep the boundary clear, keep aliases explicit, register and log the database correctly before process creation, create Replicat only after the local trail exists, and verify every layer with commands and reports rather than with status color alone.
Test your understanding
Select an answer and click Check.
Q1 — Administration Service manages processes within what boundary?
Q2 — Where are Extract and Replicat PARAMS files stored in Microservices Architecture?
Q3 — What credential store does Administration Service use to store database passwords?
Q4 — In the Administration Service web UI, which tab or section allows you to view process report files?
No comments:
Post a Comment